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 Legacy mode
In Legacy 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 Direct mode
Likewise, in Direct mode 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 mode
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, are making the secure tunnel available to aditional 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. In fact, this is a very common setup providing a solid security posture.
What permissions does the Humanitec Agent need to do what it needs to do?
The Agent is only about reachability. So it does not require premissions at all in the cloud - it needs routes, security groups, or firewall rules to let it connect to the endpoints required. These must include the API server endpoints of the Kubernetes clusters the Agent will be used to deploy workloads to. Conversely, you should restrict the Agent’s network access to any other endpoints it does not need to reach.
Is the communication one-way from the Platform Orchestrator to the Agent, or is there some backflow as well?
Requests handled by the Agent can only be initiated by the Platform Orchestrator. The requests return data. For example, when fetching Pod statuses from a Kubernetes cluster, the request originates from the Orchestrator, is routed via the Agent to the cluster, and the Pod statuses are returned to the Orchestrator.
This communication uses the secure tunnel that was previously established inside-out from the Agent to the Orchestrator, so despite the request flow originating from the Orchestrator, no inbound firewall port needs to be opened.
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. Note that a Kubernetes cluster is just one option to run the Agent, it can run anywhere in your infrastructure.
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.
Can the Agent connect back to Humanitec’s servers via a proxy?
Yes. The Agent can use HTTP Proxies that support the CONNECT method to connect back to Humanitec. This is configured via the AGENT_PROXY environment variable specified in the configuration settings. It is possible to connect to the proxy via plain HTTP or HTTPS.
Next steps
Proceed to install the Humanitec Agent into your infrastructure.