Installation
This document will guide you through the installation of the Humanitec Operator into your infrastructure.
0.1.1
Current App version:
0.9.2
Prerequisites
To get started you’ll need:
- Helm installed - version 3 or later.
- A Kubernetes (K8s) cluster version 1.23 or later.
- Access to the cluster via
kubectl
.
Install with Helm
Install the latest version of the Helm chart:
helm install humanitec-operator \
oci://registry.humanitec.io/charts/humanitec-operator \
--namespace humanitec-operator-system \
--create-namespace
To install a particular version, add a “--version
“ parameter to the command.
When using a Helm version prior to 3.8.0, you must manually enable OCI registry support. See this article for instructions.
Verify your installation
Verify that the Humanitec Operator’s controller-manager Pod is running in the target namespace:
kubectl get pods -n humanitec-operator-system
You should see this Pod in a Running
state:
NAME READY STATUS RESTARTS AGE
humanitec-operator-controller-manager-000000000-00000 2/2 Running 0 3m
Upgrade your installation
To upgrade to a particular version x.y.z
, run this command:
helm upgrade humanitec-operator \
oci://registry.humanitec.io/charts/humanitec-operator \
--namespace humanitec-operator-system \
--version <version>
Configure authentication for Drivers
To ensure secure access to Humanitec-hosted Drivers, the Humanitec Operator will have to establish its identity against the Humanitec Driver API. This is done using a private key to sign a token, which can then be validated by the Humanitec Drivers using the public key.
This step is required only if you’ll be using Humanitec-hosted Drivers. That excludes the Echo and Template Drivers whose logic is executed inside the Operator itself.
Generate public/private key pair
The following commands will generate two files openssl_private_key.pem
and openssl_public_key.pem
containing a private and corresponding and public key.
# Generate a new private key
openssl genpkey -algorithm RSA -out openssl_private_key.pem -pkeyopt rsa_keygen_bits:4096
# Extract the public key from the private key generated in the previous command
openssl rsa -in openssl_private_key.pem -outform PEM -pubout -out openssl_public_key.pem
Add a Secret to the Humanitec Operator
The public/private key pair must be made available to the Operator through a K8s Secret.
Set these environment variables:
export HUMANITEC_ORG=<your-humanitec-org-id>
export HUMANITEC_TOKEN=<your-humanitec-api-token>
where:
HUMANITEC_ORG
holds the Humanitec Organization ID (all lowercase)HUMANITEC_TOKEN
holds a valid Humanitec API Token with the Administrator role in the Organization.
Create the Secret:
kubectl --namespace humanitec-operator-system create secret generic humanitec-operator-private-key \
--from-file=privateKey=openssl_private_key.pem \
--from-literal=humanitecOrganisationID=$HUMANITEC_ORG
Register the public key with the Humanitec Platform Orchestrator
Register the public key in the Humanitec Organization:
curl https://api.humanitec.io/orgs/${HUMANITEC_ORG}/keys \
-X POST \
-H "Authorization: Bearer $HUMANITEC_TOKEN" \
-H "Content-Type: application/json" \
-d "$(cat openssl_public_key.pem | jq -sR)"
Note: the jq
command is used to encode the public key file as a JSON string.
This step completes setting up the Humanitec Operator authentication for calling Drivers. Note that this does not yet configure a specific secret store, which is done via SecretStore
custom resources in the Operator namespace. Follow one of the guides for your secret store type, e.g. HashiCorp Vault.
Clean up
It’s best to store the public/private key pair in a safe place for future use, e.g. in a secret store your organization is using. Refer to the product documentation of that store for details.
Then, remove the generated key pair from your local environment:
rm openssl_private_key.pem openssl_public_key.pem
Uninstalling
Before continuing, ensure that all Humanitec Operator resources that have been created while using it have been deleted. You can check for any existing resources with this command:
kubectl get Resources,SecretMappings,SecretStores,WorkloadPatches,Workloads -A
Once all these resources have been deleted, you’re ready to uninstall the Operator:
helm uninstall humanitec-operator -n humanitec-operator-system
Finally, delete the Humanitec Operator namespace:
kubectl delete namespace humanitec-operator-system
CRD Handling
The Humanitec Operator bundles all CRDs along with the other templates in the Helm chart. This improves ease of use and makes upgrading CRDs possible with Helm alone. The best practices described by the Helm team do not apply.
This means that if you uninstall the Helm release, the CRDs will also be uninstalled. You’ll then lose all instances of those CRDs, e.g. all SecretStore
resources in the cluster. Consider preparing a mitigation against accidental deletion so you have a means to reapply resources e.g. from an Infrastructure as Code (IaC) pattern.