Deckhouse Platform for bare metal

1
Selecting infrastructure
2
Installation information
3
Setting up cluster
4
Installation
5
Finishing installation
6
What can I do next?
Finishing installation

Add a new node to the cluster (for details, see the example of adding a static node to a cluster):

  • Start a new virtual machine that will become the cluster node.
  • Configure the StorageClass for the local storage by running the following command on the master node: 
    sudo -i d8 k create -f - << EOF
apiVersion: deckhouse.io/v1alpha1
kind: LocalPathProvisioner
metadata:
  name: localpath
spec:
  path: "/opt/local-path-provisioner"
  reclaimPolicy: Delete
EOF

  • Make the created StorageClass the default one in the cluster:

    sudo -i d8 k patch mc global --type merge \
  -p "{\"spec\": {\"settings\":{\"defaultClusterStorageClass\":\"localpath\"}}}"

  • Create a NodeGroup worker and add a node using Cluster API Provider Static (CAPS) or manually using a bootstrap script.

    • CAPS
    • Bootstrap script

    • Create a NodeGroup worker, by running the following command on the master node:

      sudo -i d8 k create -f - << EOF
apiVersion: deckhouse.io/v1
kind: NodeGroup
metadata:
  name: worker
spec:
  nodeType: Static
  staticInstances:
    count: 1
    labelSelector:
      matchLabels:
        role: worker
EOF

    • Generate a new SSH key with an empty passphrase. To do so, run the following command on the master node:

      ssh-keygen -t ed25519 -f /dev/shm/caps-id -C "" -N ""

    • Create an SSHCredentials resource in the cluster. To do so, run the following command on the master node:

      sudo -i d8 k create -f - <<EOF
apiVersion: deckhouse.io/v1alpha2
kind: SSHCredentials
metadata:
  name: caps
spec:
  user: caps
  privateSSHKey: "`cat /dev/shm/caps-id | base64 -w0`"
EOF

    • Print the public part of the previously generated SSH key (you will need it in the next step). To do so, run the following command on the master node:

      cat /dev/shm/caps-id.pub

    • Create the caps user on the virtual machine you have started. To do so, run the following command, specifying the public part of the SSH key obtained in the previous step:

      • For Ubuntu-based OS
      • For CentOS or Rocky Linux (RHEL-based OS)
      # Specify the public part of the user SSH key.
export KEY='<SSH-PUBLIC-KEY>'
useradd -m -s /bin/bash caps
usermod -aG sudo caps
echo 'caps ALL=(ALL) NOPASSWD: ALL' | sudo EDITOR='tee -a' visudo
mkdir /home/caps/.ssh
echo $KEY >> /home/caps/.ssh/authorized_keys
chown -R caps:caps /home/caps
chmod 700 /home/caps/.ssh
chmod 600 /home/caps/.ssh/authorized_keys

      # Specify the public part of the user SSH key.
export KEY='<SSH-PUBLIC-KEY>'
useradd -m -s /bin/bash caps
usermod -aG wheel caps
echo 'caps ALL=(ALL) NOPASSWD: ALL' | sudo EDITOR='tee -a' visudo
mkdir /home/caps/.ssh
echo $KEY >> /home/caps/.ssh/authorized_keys
chown -R caps:caps /home/caps
chmod 700 /home/caps/.ssh
chmod 600 /home/caps/.ssh/authorized_keys

    • Create a StaticInstance for the node to be added. To do so, run the following command on the master node (specify IP address of the node):

      # Specify the IP address of the node you want to connect to the cluster.
export NODE=<NODE-IP-ADDRESS>
sudo -i d8 k create -f - <<EOF
apiVersion: deckhouse.io/v1alpha2
kind: StaticInstance
metadata:
  name: d8cluster-worker
  labels:
    role: worker
spec:
  address: "$NODE"
  credentialsRef:
    kind: SSHCredentials
    name: caps
EOF

  • If you have added additional nodes to the cluster, ensure they are Ready.

    On the master node, run the following command to get nodes list:

    sudo -i d8 k get no

    Example of the output...

    sudo -i d8 k get no
NAME               STATUS   ROLES                  AGE    VERSION
d8cluster          Ready    control-plane,master   30m   v1.33.13
d8cluster-worker   Ready    worker                 10m   v1.33.13

Adding two or more worker nodes...

Bootstrap script:
Use the same NodeGroup worker and the same bootstrap script you used to add the first node. For each additional node:

  1. Prepare a clean virtual machine.

  2. On this VM, run the command with the same Base64-encoded script you used to add the first node:

    echo <BASE64-SCRIPT-CODE> | base64 -d | bash

CAPS:
If you use CAPS and want to add more static nodes in the worker NodeGroup:

  1. Increase the value of spec.staticInstances.count in the NodeGroup worker resource up to the required number of nodes.
  2. Create one StaticInstance resource for each new node, specifying:

Note that it may take some time to get all Deckhouse components up and running after the installation is complete.

  • Make sure the Kruise controller manager is Ready before continuing.

    On the master node, run the following command:

    sudo -i d8 k -n d8-ingress-nginx get po -l app=kruise

    Example of the output...

    $ sudo -i d8 k -n d8-ingress-nginx get po -l app=kruise
NAME                                         READY   STATUS    RESTARTS    AGE
kruise-controller-manager-7dfcbdc549-b4wk7   3/3     Running   0           15m

Next, you will need to create an Ingress controller, a user to access the web interfaces, and configure the DNS.

  • Setting up an Ingress controller

    On the master node, create the ingress-nginx-controller.yml file containing the Ingress controller configuration:

    # Section containing the parameters of Ingress NGINX Controller.
# https://deckhouse.io/modules/ingress-nginx/cr.html
apiVersion: deckhouse.io/v1
kind: IngressNginxController
metadata:
  name: nginx
spec:
  ingressClass: nginx
  # The way traffic goes to cluster from the outer network.
  inlet: HostPort
  hostPort:
    httpPort: 80
    httpsPort: 443
  # Describes on which nodes the Ingress Controller will be located.
  # Configuration examples:
  # https://deckhouse.io/modules/ingress-nginx/examples.html
  # You might consider changing this.
  nodeSelector:
    node-role.kubernetes.io/control-plane: ""
  tolerations:
  - effect: NoSchedule
    key: node-role.kubernetes.io/control-plane
    operator: Exists

    Apply it using the following command on the master node:

    sudo -i d8 k create -f $PWD/ingress-nginx-controller.yml

    It may take some time to start the Ingress controller after installing Deckhouse. Make sure the Ingress controller has started before continuing (run on the master node):

    sudo -i d8 k -n d8-ingress-nginx get po -l app=controller
    Wait for the Ingress controller pods to switch to Ready state.

    Example of the output...

    $ sudo -i d8 k -n d8-ingress-nginx get po -l app=controller
NAME                                       READY   STATUS    RESTARTS   AGE
controller-nginx-r6hxc                     3/3     Running   0          5m

  • Create a user to access the cluster web interfaces

    Create on the master node the user.yml file containing the user account data and access rights:

    apiVersion: deckhouse.io/v1
kind: ClusterAuthorizationRule
metadata:
  name: admin
spec:
  # Kubernetes RBAC accounts list
  subjects:
  - kind: User
    name: admin@deckhouse.io
  # pre-defined access template
  accessLevel: SuperAdmin
  # allow user to do kubectl port-forward
  portForwarding: true
---
# section containing the parameters of the static user
# version of the Deckhouse API
apiVersion: deckhouse.io/v1
kind: User
metadata:
  name: admin
spec:
  # user e-mail
  email: admin@deckhouse.io
  # this is a hash of the password <GENERATED_PASSWORD>, generated  now
  # generate your own or use it at your own risk (for testing purposes)
  # echo -n '<GENERATED_PASSWORD>' | htpasswd -BinC 10 "" | cut -d: -f2 | tr -d '\n' | base64 -w0; echo
  # you might consider changing this
  password: <GENERATED_PASSWORD_HASH>

    Apply it using the following command on the master node:

    sudo -i d8 k create -f $PWD/user.yml
  • Create DNS records to organize access to the cluster web interfaces.

    If you use sslip.io or a similar wildcard DNS service as the cluster DNS name template, there is no need to create DNS records manually.

    The domain in the template must not match the domain from the clusterDomain parameter or the internal network service zone. Example: clusterDomain: cluster.local (default value), the network service zone is central1.internal. In this case, publicDomainTemplate cannot be %s.cluster.local or %s.central1.internal.

    Find out the public IP address of the node where the Ingress controller is running. Configure DNS in one of the following ways:

    • Wildcard DNS record
    • Individual DNS records
    • Hosts file

    Use this option if you have a DNS server and your cluster DNS name template is a wildcard template (e.g., %s.kube.company.my).

    On the DNS server, add a wildcard A record containing this public IP address.

    Use this option if you have a DNS server and your cluster DNS name template is not a wildcard template (e.g., %s-kube.company.my).

    On the DNS server, add A or CNAME records containing this public IP address for the DNS names from the list. The names in the list are built from the DNS name template you specified when configuring the installation:

    api.example.com
code.example.com
commander.example.com
console.example.com
dex.example.com
documentation.example.com
grafana.example.com
hubble.example.com
istio.example.com
istio-api-proxy.example.com
kubeconfig.example.com
openvpn-admin.example.com
prometheus.example.com
registry.example.com
status.example.com
stronghold.example.com
tools.example.com
upmeter.example.com

    The list above contains the DNS names that a cluster deployed using this guide requires. The complete list is given in the “List of Reserved Deckhouse Platform DNS Names” section of the documentation.

    Use this option if you don’t have a DNS server. On the computer from which you need access to Deckhouse services, add static records to the hosts file (/etc/hosts for Linux, %SystemRoot%\system32\drivers\etc\hosts for Windows). Each record maps a service name to the public IP address of the node where the Ingress controller is running.

    To get the command for adding the records, use the hosts file data generator: enter the DNS name template and the public IP address of the node where the Ingress controller is running.

    Go back Next: What can I do next?