Installation

Prerequisites

Before installing, ensure the following prerequisites are met :

  • Have a Kubernetes or OpenShift cluster in a version that’s supported by cert-manager;

  • Have helm on a device with administrative access to the cluster (required to install CRDs);

  • The cluster can either pull images from Internet or a proxy has been set up for registry.evertrust.io;

  • Have access to an Horizon instance in a supported Horizon version.

Install

Install cert-manager

As horizon-issuer is a cert-manager issuer, cert-manager must be installed in the cluster before installing horizon-issuer. If not already installed, head to the Releases section on the cert-manager website and find the latest version.

  • Helm

  • YAML manifests

$ helm install \
 cert-manager oci://quay.io/jetstack/charts/cert-manager \
 --version <version> \ (1)
 --namespace cert-manager \
 --create-namespace \
 --set crds.enabled=true
1 Replace with the version to install.

For details about configurable settings, head to Artifact Hub.

$ kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/<version>/cert-manager.yaml

Replace <version> with the version to install.

Other installation methods (such as cmctl) are available on the cert-manager installation documentation.

Install horizon-issuer

Similarly to cert-manager, we offer either a Helm chart or YAML manifests to install horizon-issuer:

  • Helm

  • YAML manifests

Add the EVERTRUST Helm repository:

$ helm repo add evertrust https://repo.evertrust.io/repository/charts

Then, install the chart:

$ helm install horizon-issuer evertrust/horizon-issuer -- version <version>
CRD considerations

horizon-issuer needs CRDs to properly work. Similarly to what cert-manager offers, you have two options when installing the chart :

  • Manage CRDs manually: manually install the CRDs using kubectl. In that case, the following commands before installing or upgrading the chart:

    kubectl apply -f https://raw.githubusercontent.com/evertrust/horizon-issuer/v0.3.0/charts/horizon-issuer/crds/horizon.evertrust.io_clusterissuers.yaml
kubectl apply -f https://raw.githubusercontent.com/evertrust/horizon-issuer/v0.3.0/charts/horizon-issuer/crds/horizon.evertrust.io_issuers.yaml

    This ensures that the CRDs are not upgraded by mistake. However, it requires you to manually upgrade the CRDs when a new version is released. If you opt for this method, ensure that the installCRDs key is set to false in your Helm.

  • Let the Helm chart manage CRDs: in that case, the CRDs will be installed and upgraded automatically when installing or upgrading the chart. To do so, ensure that the installCRDs key is set to true in your Helm.

 
$ kubectl apply -f https://github.com/evertrust/horizon-issuer/releases/download/<version>/install.yaml

Upgrade

Unless noted otherwise in the below upgrade notes, upgrading horizon-issuer is not expected to break existing behaviors. horizon-issuer having reached 1.0.0, we’ll follow semantic versioning and denote any breaking changes by releasing a new major version.

  • Helm

  • YAML manifests

Update the EVERTRUST Helm repository:

$ helm repo update evertrust

Then, install the chart:

$ helm upgrade horizon-issuer evertrust/horizon-issuer --version <version>

Simply apply the new manifests which should update components:

$ kubectl apply -f https://github.com/evertrust/horizon-issuer/releases/download/<version>/install.yaml

Specific upgrade notes

Upgrade from v0.3 to v1.0

The Helm Chart has been completely reworked to be generated from the YAML manifests. Therefore, many keys in the values.yaml files have changed. See the reference values.yaml files to check with your local configuration for updates. Namely:

  • installCRDs has been renamed to crd.enable and set to true by default;

  • the image block has been moved to manager.image

Additionally, the already deprecated CRD version v1alpha1 has been removed in favor of the current v1beta1.

Upgrade from v0.2.0 to v0.3.0

In 0.3.0, the CRDs can be managed by the Helm chart itself, similarly to what cert-manager offers. It means that you have two options when upgrading.

Should you decide to manage CRDs automatically through the Helm chart, you’ll need to update existing CRDs before upgrading so that they can be managed by the Helm chart. The following commands are required :

$ kubectl label crd/clusterissuers.horizon.evertrust.io app.kubernetes.io/managed-by=Helm
$ kubectl label crd/issuers.horizon.evertrust.io app.kubernetes.io/managed-by=Helm
$ kubectl annotate crd/clusterissuers.horizon.evertrust.io meta.helm.sh/release-name=<horizon-issuer> meta.helm.sh/release-namespace=<horizon-issuer>
$ kubectl annotate crd/issuers.horizon.evertrust.io meta.helm.sh/release-name=<horizon-issuer> meta.helm.sh/release-namespace=<horizon-issuer>

Replace replace release-name with your Helm release name and release-namespace with the namespace you’re installing into.

Upgrade from v0.1.0 to v0.2.0

In 0.2.0, the new CRD version is v1beta1, and v1alpha1 is no longer supported. To migrate from the old version, you must first upgrade the CRDs:

$ kubectl apply -f https://raw.githubusercontent.com/evertrust/horizon-issuer/v0.2.0/charts/horizon-issuer/crds/horizon.evertrust.io_clusterissuers.yaml
$ kubectl apply -f https://raw.githubusercontent.com/evertrust/horizon-issuer/v0.2.0/charts/horizon-issuer/crds/horizon.evertrust.io_issuers.yaml

This will not delete your existing Issuer and ClusterIssuer objects, but will allow you to create resources with the new v1beta1 version. After having re-created your issuer objects, you can start the upgrade using Helm :

$ helm upgrade horizon-issuer evertrust/horizon-issuer

Uninstall

  • Helm

  • YAML manifests

Simply uninstall the chart:

$ helm uninstall horizon-issuer

Simply delete the manifests using kubectl:

$ kubectl delete -f https://github.com/evertrust/horizon-issuer/releases/download/<version>/install.yaml

Uninstalling horizon-issuer will delete any Issuer or ClusterIssuer resources created in the cluster. Make sure to backup the configuration properly before uninstalling.