How do I find out all Deckhouse parameters?
All the essential Deskhouse settings (including module parameters) are stored in the deckhouse
ConfigMap in the d8-system
namespace.
To view Deckhouse settings use the following command:
kubectl -n d8-system get cm deckhouse -o yaml
How do I find the documentation for the version installed?
Documentation in the cluster is available when the deckhouse-web module is enabled (it is enabled by default except the
Minimal
bundle).
The documentation for the Deckhouse version running in the cluster is available at deckhouse.<cluster_domain>
, where <cluster_domain>
is the DNS name that matches the template defined in the global.modules.publicDomainTemplate
parameter.
How do I set the desired release channel?
Change (set) the releaseChannel
parameter in the deckhouse
module configuration to automatically switch to another release channel.
It will activate the mechanism of automatic stabilization of the release channel.
Here is an example of the module configuration:
deckhouse: |
releaseChannel: Stable
How do I disable automatic updates?
To completely disable the Deckhouse update mechanism, remove the releaseChannel
parameter in the `deckhouse’ module configuration.
In this case, Deckhouse does not check for updates and even doesn’t apply patch releases.
It is highly not recommended to disable automatic updates! It will block updates to patch releases that may contain critical vulnerabilities and bugs fixes.
How does automatic Deckhouse update work?
Every minute Deckhouse checks a new release appeared in the release channel specified by the releaseChannel
parameter.
When a new release appears on the release channel, Deckhouse downloads it and creates CustomResource DeckhouseRelease
.
After creating a DeckhouseRelease
CR in a cluster, Deckhouse updates the deckhouse
Deployment and sets the image tag to a specified release tag according to selected update mode and update windows (automatic at any time by default).
To get list and status of all releases use the following command:
kubectl get deckhousereleases
Patch releases (e.g., an update from version
1.30.1
to version1.30.2
) ignore update windows settings and apply as soon as they are available.
Change the release channel
- When switching to a more stable release channel (e.g., from
Alpha
toEarlyAccess
), Deckhouse downloads release data from the release channel (theEarlyAccess
release channel in the example) and compares it with the existingDeckhouseReleases
:- Deckhouse deletes later releases (by semver) that have not yet been applied (with the
Pending
status). - if the latest releases have been already Deployed, then Deckhouse will hold the current release until a later release appears on the update channel (on the
EarlyAccess
release channel in the example).
- Deckhouse deletes later releases (by semver) that have not yet been applied (with the
- When switching to a less stable release channel (e.g., from
EarlyAcess
toAlpha
), the following actions take place:- Deckhouse downloads release data from the release channel (the
Alpha
release channel in the example) and compares it with the existingDeckhouseReleases
. - Then Deckhouse performs the update according to the update parameters.
- Deckhouse downloads release data from the release channel (the
How do I run Deckhouse on a particular node?
Set the nodeSelector
parameter of the deckhouse
module and avoid setting tolerations
. The necessary values will be assigned to the tolerations
parameter automatically.
You should also avoid using CloudEphemeral nodes. Otherwise, a situation may occur when the target node is not in the cluster and node ordering for some reason is impossible.
Here is an example of the module configuration:
deckhouse: |
nodeSelector:
node-role.deckhouse.io/deckhouse: ""
How do I configure Deckhouse to use a third-party registry?
Deckhouse can be configured to work with a third-party registry (e.g., a proxy registry inside private environments).
Configuring
Define the following parameters in the InitConfiguration
resource:
imagesRepo: <PROXY_REGISTRY>/<DECKHOUSE_REPO_PATH>/<DECKHOUSE_REVISION>
. The path to the Deckhouse image in the third-party registry matching the edition used (CE/EE/FE), for exampleimagesRepo: registry.deckhouse.io/deckhouse/ce
;registryDockerCfg: <BASE64>
. Base64-encoded auth credentials of the third-party registry.
Use the following registryDockerCfg
if anonymous access to Deckhouse images is allowed in the third-party registry:
{"auths": { "<PROXY_REGISTRY>": {}}}
registryDockerCfg
must be Base64-encoded.
Use the following registryDockerCfg
if authentication is required to access Deckhouse images in the third-party registry:
{"auths": { "<PROXY_REGISTRY>": {"username":"<PROXY_USERNAME>","password":"<PROXY_PASSWORD>","auth":"<AUTH_BASE64>"}}}
<PROXY_USERNAME>
— auth username for<PROXY_REGISTRY>
.<PROXY_PASSWORD>
— auth password for<PROXY_REGISTRY>
.<PROXY_REGISTRY>
— registry address:<HOSTNAME>[:PORT]
.<AUTH_BASE64>
— Base64-encoded<PROXY_USERNAME>:<PROXY_PASSWORD>
auth string.
registryDockerCfg
must be Base64-encoded.
The InitConfiguration
resource provides two more parameters for non-standard third-party registry configurations:
registryCA
- root CA certificate to validate the third-party registry’s HTTPS certificate (if self-signed certificates are used);registryScheme
- registry scheme (http
orhttps
). The default value ishttps
.
Installing
Use the dhctl
’s --dont-use-public-control-plane-images
key to instruct Deckhouse to use control-plane
images from the third-party registry instead of the public one (k8s.gcr.io
).
Tips for configuring the third-party registry
Note that Deckhouse only supports Bearer authentication for registries.
Nexus
The following parameters must be set if the Nexus repository manager is used:
-
Enable
Docker Bearer Token Realm
: -
Enable anonymous registry access (otherwise, Bearer authentication won’t work):
-
Set the
Maximum metadata age
to 0 (otherwise, the automatic update of Deckhouse will fail due to caching):
Harbor
You need to use the Proxy Cache feature of a Harbor.
- Create a Registry:
Administration -> Registries -> New Endpoint
.Provider
:Docker Registry
.Name
— specify any of your choice.Endpoint URL
:https://registry.deckhouse.io
.- Specify the
Access ID
andAccess Secret
if you use Deckhouse Enterprise Edition; otherwise, leave them blank.
- Create a new Project:
Projects -> New Project
.Project Name
will be used in the URL. You can choose any name, for example,d8s
.Access Level
:Public
.Proxy Cache
— enable and choose the Registry, created in the previous step.
Thus, Deckhouse images will be available at https://your-harbor.com/d8s/deckhouse/{d8s-edition}:{d8s-version}
.
How do I switch a running Deckhouse cluster to use a third-party registry?
To switch the Deckhouse cluster to using a third-party registry, follow these steps:
- Update the
image
field in thed8-system/deckhouse
deployment to contain the address of the Deckhouse image in the third-party-registry; - Edit the
d8-system/deckhouse-registry
secret (note that all parameters are Base64-encoded):- Insert third-party registry credentials into
.dockerconfigjson
. - Replace
address
with the third-party registry’s host address (e.g.,registry.example.com
). - Change
path
to point to a repo in the third-party registry (e.g.,/deckhouse/fe
). - If necessary, change
scheme
tohttp
(if the third-party registry uses HTTP scheme). - If necessary, change or add the
ca
field with the root CA certificate that validates the third-party registry’s https certificate (if the third-party registry uses self-signed certificates).
- Insert third-party registry credentials into
- Wait for the Deckhouse Pod to become
Ready
. Restart Deckhouse Pod if it will be inImagePullBackoff
state. - Wait for bashible to apply the new settings on the master node. The bashible log on the master node (
journalctl -u bashible
) should contain the messageConfiguration is in sync, nothing to do
. - Only if Deckhouse won’t be updated using a third-party registry, then you have to remove
releaseChannel
setting from configmapd8-system/deckhouse
.