What is the Humanitec Operator?

The Humanitec Operator is a Kubernetes (K8s) operator that controls Deployments made with the Humanitec Platform Orchestrator. Since Humanitec Resources creation can depend on secrets, the Humanitec Operator is also capable of and responsible for provisioning the required Kubernetes Secret resources in the cluster.

You need to use the Humanitec Operator when any of the following holds true:

  • You wish to store secrets in your own secrets store instead of the default store used by the Humanitec SaaS solution.
  • You wish to follow a GitOps approach for managing Kubernetes objects using a tool such as ArgoCD or Flux.
  • You do not wish to expose your cluster API server endpoint to the Humanitec Platform Orchestrator.


The Humanitec Operator is installed via a Helm chart once per cluster. Its controller-manager Pod acts on resources based on CRDs that come with the chart. The Operator communicates back to Humanitec-hosted drivers through a secure channel. See the Installation guide for details.


The Humanitec Operator is motivated by the need to manage secrets in an Internal Developer Platform (IDP). Secrets must be handled in various places when using the Humanitec Platform Orchestrator, e.g. as shared values and secrets for Applications, for certain types of Resource Definitions, or when configuring Drivers.

Modes of operation

The Humanitec Operator introduces an architecture element that lets you connect your own secret stores for managing those secrets. There are three main modes of operation, starting with the default setup without the Humanitec Operator. See the Architecture guide for more details.

Direct Cluster: Without the Humanitec Operator, the Platform Orchestrator uses its own secret store. It performs all Application deployments and provisioning of infrastructure via Drivers.

Humanitec Operator: The Platform Orchestrator provides instructions to the Humanitec Operator via custom resources. The Operator performs Application Deployments and provisioning of infrastructure via Drivers, accessing your internal secret store to obtain required secrets.

GitOps: The Platform Orchestrator writes custom resource manifests to a Git repository instead of to the cluster, and a GitOps operator pulls those manifests into the cluster itself.

Multiple secret stores

Multiple secret stores can be configured for the Humanitec Operator or GitOps mode. Doing that requires you to use secret references to indicate the store for a particular secret.

The Humanitec Operator in a self-hosting scenario

When you’re self-hosting the Platform Orchestrator, using the Humanitec Operator is optional. The same considerations concerning the reachability of the cluster API server and secret store access apply. The only difference is that they are now evaluated inside the infrastructure you control.

Connecting secret stores

To start using your internal secret stores, connect them to the Humanitec Operator and Platform Orchestrator. We currently support the following types of stores, please see the individual pages for instructions on how to connect them:


The following limitations apply when using the Humanitec Operator.

  • You cannot use the Humanitec “Default” Resource Definitions because they store secrets in Humanitec’s own secret store which is not accessible to the Operator.
  • Resources of type k8s-cluster, k8s-namespace, agent, and logging are always provisioned by the Platform Orchestrator, not the Operator. They are therefore subject to these limitations:

Next steps

Familiarize yourself with the architecture of the operator and the security benefits it brings, and proceed to installing it into your infrastructure.