Overview

What is the Humanitec Agent? #

The Humanitec Agent can be used to provide a secure and easy-to-administer way for the Humanitec Platform Orchestrator to access private endpoints in the customer’s infrastructure.

It is intended to be run inside the customer’s infrastructure in such a way that it has network connectivity to the necessary systems the Platform Orchestrator needs access to.

The Humanitec Agent supports these use cases:

• You wish to deploy Workloads to a target Kubernetes cluster without publicly exposing the cluster’s API server. Such clusters are often called “private clusters”.
• You wish to utilize internal systems to provision Resources for your Workloads.
  • E.g. you need to access database servers on your private network to provision additional databases.
  • This capability is currently being developed.

How it works #

The Humanitec Agent establishes a secure tunnel to Humanitec’s servers. This requires outbound network traffic on TCP port 443 only, so you do not need to open any ports on your perimeter or expose any additional endpoints. A public/private key pair uniquely identifies the Agent.

The Platform Orchestrator can then make requests via this tunnel to the Agent, which will forward those requests onto the target systems.

Run anywhere in your infrastructure #

The Humanitec Agent is provided as a single container image and can be run anywhere in your infrastructure where you can run a container. See the Installation guide for details on setting up an Agent instance.

Deploy to clusters on private networks #

Deploying Workloads to clusters on private networks is the core benefit of using the Humanitec Agent. Deployments work much the same way as for public clusters. Looking at the modes of operation described in the Humanitec Operator Architecture guide, the only difference is a shift of network traffic through the Agent, with everything else left unchanged.

You can select which clusters shall use the Humanitec Agent for Deployments. Head to our How-to guide for the details on the required configuration.

Humanitec Agent with Direct Cluster mode #

In “Direct Cluster” mode (i.e. without using the Humanitec Operator), the Platform Orchestrator deploys the same Kubernetes manifests, with secrets retrieved from the Humanitec secret store.

Humanitec Agent with Humanitec Operator mode #

Likewise, in “Humanitec Operator” mode, the Platform Orchestrator deploys the same Kubernetes custom resources (CRs), with secrets retrieved from your own secret store by the Operator to provision the full manifests.

Humanitec Agent with GitOps #

The “Humanitec Operator with GitOps” mode cannot be combined with the Humanitec Agent. The GitOps approach does not install anything to a cluster, it only uploads custom resource manifests to a Git repository. If your Git service is also on the internal network and can’t be reached by the Platform Orchestrator, you can instead use the Humanitec Agent in one of the modes shown above.

Drivers accessing other internal systems #

Besides deploying Workloads to Kubernetes clusters, we plan to make the secure tunnel available to other Drivers, to provision infrastructure only reachable on internal endpoints.

In any case, the Humanitec Agent can only ever be used with Humanitec-hosted drivers. This is because the secure tunnel exists between Humanitec’s network and the customer network, and Drivers hosted elsewhere will not be able to utilize it.

Agent authentication #

The Humanitec Agent authenticates towards the Platform Orchestrator by signing a token with its private key. The Platform Orchestrator can validate the signature using the Agent’s public key which is part of the Agent registration within an Organization.

An Agent operates using one particular public/private key pair at any time. On the Platform Orchestrator side, you can link multiple keys to the same Agent registration. This is useful when performing a key rotation.

FAQ #

Can the Humanitec Agent and the Humanitec Operator coexist in the same Organization? #

Yes. You can use the Humanitec Agent to deploy Workloads to a private cluster, and the Humanitec Operator to utilize your own secret store, as shown in the diagram above.

Can the Humanitec Agent and the Humanitec Operator coexist on the same cluster? #

Yes, these two components operate independently from each other. We recommend installing them into different namespaces when sharing the same cluster.

Can I register the same Humanitec Agent to multiple Organizations? #

Yes. On the Platform Orchestrator side you need to register the Agent separately with each Organization. Any key rotation for the Agent must be performed for each Organization as well.

On the Agent installation side, name all applicable Organizations in the configuration settings for the Agent.

Can I run multiple replicas of the same logical Agent? #

Yes, you can run multiple replicas of an Agent sharing the same public key and Agent ID for greater reliability. The Platform Orchestrator will distribute traffic among the available replicas. There is an optional configuration setting to name individual replicas.

Do I need to reference the Humanitec Agent in Score files? #

No. Usage of the Humanitec Agent is transparent to developers using Score. The Agent is not a kind of Resource that you connect to a Workload directly. Technically speaking, it’s a Resource Type with an indirect use.

Next steps #

Proceed to install the Humanitec Agent into your infrastructure.