Installation process

Domino provides install automation tools that use Helm to deploy the Domino platform into your compatible cluster. The installer is delivered in a Docker container and runs inside the cluster.

../_images/install-diagram.png

Note that this process requires the cluster itself have access to quay.io and domino.tech to retrieve images of Domino components.




Requirements

The install automation tools are delivered as a Docker image, and need to run on an installation workstation that meets the following requirements:

Additionally, you will need credentials for an installation service account that can access the Domino upstream image repositories in quay.io. Throughout these instructions, these credentials will be referred to as $QUAY_USERNAME and $QUAY_PASSWORD. Contact your Domino account team if you need new credentials.

The hosting cluster will need access to the following domains via Internet to retrieve component and dependency images:

  • quay.io
  • domino.tech
  • k8s.gcr.io
  • docker.elastic.co
  • docker.io
  • gcr.io



Install process

  1. Connect to a workstation that meets the install automation requirements listed above.

  2. Log in to quay.io with the credentials described in the requirements section above.

    docker login quay.io
    
  3. Retrieve the Domino installer image from quay.io.

    docker pull quay.io/domino/fleetcommand-agent:v21
    
  4. Initialize the installer application to generate a template configuration file named domino.yml.

    docker run --rm -it \
      -v $(pwd):/install \
      quay.io/domino/fleetcommand-agent:v21 \
      init --file /install/domino.yml
    
  5. Edit the configuration file with all necessary details about the target cluster, storage systems, and hosting domain. Read the configuration reference for more information about available keys, and consult the configuration examples for guidance on getting started.

    Note that you should change the value of name from domino-deployment to something that identifies the purpose of your installation and contains the name of your organization.

  6. Run this install script from the directory with the finalized configuration file to install Domino into the cluster. Note that you must fill in your $QUAY_USERNAME and $QUAY_PASSWORD where indicated, and also note that this script assumes your installer configuration file is in the same directory, and is named exactly domino.yml.

    #!/bin/bash
    
    set -ex
    
    kubectl delete po --ignore-not-found=true fleetcommand-agent-install
    
    kubectl create secret \
      docker-registry \
      -o yaml --dry-run \
      --docker-server=quay.io \
      --docker-username=$QUAY_USERNAME \
      --docker-password=$QUAY_PASSWORD \
      --docker-email=. domino-quay-repos | kubectl apply -f -
    
    kubectl create configmap \
      fleetcommand-agent-config \
      -o yaml --dry-run \
      --from-file=domino.yml | kubectl apply -f -
    
    cat <<EOF | kubectl apply -f -
    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: admin
    ---
    apiVersion: rbac.authorization.k8s.io/v1
    kind: ClusterRoleBinding
    metadata:
      name: admin-default
    roleRef:
      apiGroup: rbac.authorization.k8s.io
      kind: ClusterRole
      name: cluster-admin
    subjects:
    - kind: ServiceAccount
      name: admin
      namespace: default
    ---
    apiVersion: v1
    kind: Pod
    metadata:
      name: fleetcommand-agent-install
    spec:
      serviceAccountName: admin
      imagePullSecrets:
        - name: domino-quay-repos
      restartPolicy: Never
      containers:
      - name: fleetcommand-agent
        image: quay.io/domino/fleetcommand-agent:v21
        args: ["run", "-f", "/app/install/domino.yml", "-v"]
        imagePullPolicy: Always
        volumeMounts:
        - name: install-config
          mountPath: /app/install/
      volumes:
      - name: install-config
        configMap:
          name: fleetcommand-agent-config
    EOF
    
    set +e
    while true; do
      sleep 5
      if kubectl logs -f fleetcommand-agent-install; then
        break
      fi
    done
    
  7. The installation process can take up to 30 minutes to fully complete. The installer will output verbose logs and surface any errors it encounters, but it can also be useful to follow along in another terminal tab by running:

    kubectl get pods --all-namespaces
    

    This will show the status of all pods being created by the installation process. If you see any pods enter a crash loop or hang in a non-ready state, you can get logs from that pod by running:

    kubectl logs $POD_NAME --namespace $NAMESPACE_NAME
    

    If the installation completes successfully, you should see a message that says:

    2019-11-25 21:20:20,214 - INFO - fleetcommand_agent.Application - Deployment complete.
    Domino is accessible at $YOUR_FQDN
    

    However, the application will only be accessible via HTTPS at that FQDN if you have configured DNS for the name to point to an ingress load balancer with the appropriate SSL certificate that forwards traffic to your platform nodes.




Upgrading

Upgrading a Domino deployment is a simple process of running the installer again with the same configuration, but with the version field set the value of the desired upgrade version. See the installer configuration reference and the installer release notes for information on the Domino versions your installer can support.

If you need to upgrade to a newer installer version to upgrade to your desired Domino version, use the process below.

  1. Retrieve the new Domino installer image from quay.io by filling in the desired <version> value in the command below

    docker pull quay.io/domino/fleetcommand-agent:<version>
    
  2. Move your existing domino.yml configuration file to another directory, or rename it.

  3. Generate a new domino.yml configuration template by running the initialization command through the new version of the installer. This will ensure you have a configuration schema conformant to the new version.

    docker run --rm -it \
      -v $(pwd):/install \
      quay.io/domino/fleetcommand-agent:<version> \
      init --file /install/domino.yml
    
  4. Copy the values from your old configuration into the new file.

  5. When complete, run the install script from the install process, being sure to change the spec.containers.image value to quay.io/domino/fleetcommand-agent:<version> with the appropriate version.