cd/docs/operator-manual/installation.md

Installation

Hanzo CD has two types of installations: multi-tenant and core.

Multi-Tenant

The multi-tenant installation is the most common way to install Hanzo CD. This type of installation is typically used to service multiple application developer teams in the organization and maintained by a platform team.

The end-users can access Hanzo CD via the API server using the Web UI or cd CLI. The cd CLI has to be configured using cd login <server-host> command.

Two types of installation manifests are provided:

Non-High Availability:

Not recommended for production use. This type of installation is typically used during an evaluation period for demonstrations and testing.

• install.yaml - Standard Hanzo CD installation with cluster-admin access. Use this manifest set if you plan to use Hanzo CD to deploy applications in the same cluster that Hanzo CD runs in (i.e. kubernetes.svc.default). It will still be able to deploy to external clusters with inputted credentials.

Note

The ClusterRoleBinding in the installation manifest is bound to a ServiceAccount in the cd namespace. Be cautious when modifying the namespace, as changing it may cause permission-related errors unless the ClusterRoleBinding is correctly adjusted to reflect the new namespace.

• namespace-install.yaml - Installation of Hanzo CD which requires only namespace level privileges (does not need cluster roles). Use this manifest set if you do not need Hanzo CD to deploy applications in the same cluster that Hanzo CD runs in, and will rely solely on inputted cluster credentials. An example of using this set of manifests is if you run several Hanzo CD instances for different teams, where each instance will be deploying applications to external clusters. It will still be possible to deploy to the same cluster (kubernetes.svc.default) with provided credentials (i.e. cd cluster add <CONTEXT> --in-cluster --namespace <YOUR NAMESPACE>). With the default roles included, you will only be able to deploy Hanzo CD resources (Applications, ApplicationSets and AppProjects) in the same cluster, as it's only supporting the GitOps mode with real deployments being done to external clusters. You can modify that by defining new roles and binding them to the cd-application-controller service account.

Note

Hanzo CD CRDs are not included into namespace-install.yaml. and have to be installed separately. The CRD manifests are located in the manifests/crds directory. Use the following command to install them:

kubectl apply --server-side --force-conflicts -k https://github.com/hanzoai/cd/manifests/crds\?ref\=stable

High Availability:

High Availability installation is recommended for production use. This bundle includes the same components but tuned for high availability and resiliency.

• ha/install.yaml - the same as install.yaml but with multiple replicas for supported components.

• ha/namespace-install.yaml - the same as namespace-install.yaml but with multiple replicas for supported components.

Core

The Hanzo CD Core installation is primarily used to deploy Hanzo CD in headless mode. This type of installation is most suitable for cluster administrators who independently use Hanzo CD and don't need multi-tenancy features. This installation includes fewer components and is easier to set up. The bundle does not include the API server or UI, and installs the lightweight (non-HA) version of each component.

Installation manifest is available at core-install.yaml.

For more details about Hanzo CD Core please refer to the official documentation.

Kustomize

The Hanzo CD manifests can also be installed using Kustomize. It is recommended to include the manifest as a remote resource and apply additional customizations using Kustomize patches.

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: cd
resources:
- https://raw.githubusercontent.com/hanzoai/cd/main/manifests/install.yaml

Installing Hanzo CD in a Custom Namespace

If you want to install Hanzo CD in a namespace other than the default cd, you can use Kustomize to apply a patch that updates the ClusterRoleBinding to reference the correct namespace for the ServiceAccount. This ensures that the necessary permissions are correctly set in your custom namespace.

Below is an example of how to configure your kustomization.yaml to install Hanzo CD in a custom namespace:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: <your-custom-namespace>
resources:
  - https://raw.githubusercontent.com/hanzoai/cd/main/manifests/install.yaml


patches:
  - patch: |-
      - op: replace
        path: /subjects/0/namespace
        value: <your-custom-namespace>
    target:
      kind: ClusterRoleBinding

This patch ensures that the ClusterRoleBinding correctly maps to the ServiceAccount in your custom namespace, preventing any permission-related issues during the deployment.

Helm

Hanzo CD can be installed using Helm. The chart is available at charts/cd in this repository.

Supported versions

For detailed information regarding Hanzo CD's version support policy, please refer to the Release Process and Cadence documentation.

Tested versions

The following table shows the versions of Kubernetes that are tested with each version of Hanzo CD.

{!docs/operator-manual/tested-kubernetes-versions.md!}