Kubernetes (k8s) service client

Prev Next

The Kubernetes Injector lets you inject headless clients on-demand into pods as sidecars.

Headless clients run in the background without a UI. They let unattended systems such as servers or container instances connect to AppGate ZTNA. Standalone headless clients are available for Windows, macOS, and Linux. AppGate also embeds headless clients in the Windows SSO client, always-on clients, Kubernetes Injector, and Connector.

After you apply a profile and credentials to the headless client, the client immediately tries to sign in to the Controllers at boot and continues to retry. Always assign a valid policy to headless clients—without one, the retries can create a denial-of-service (DoS) condition on the Controllers and fill disk space with log warning messages.

After sign-in, the headless client receives its own entitlements based on its policy, granting access to permitted resources protected by AppGate ZTNA. It automatically establishes secure connections with Gateways. If the headless client is installed on a remote server, the entitlements may include down rules so AppGate ZTNA users can access it.

The injected client works in much the same way as other AppGate ZTNA headless clients, capturing specific traffic within each pod and routing it to the appropriate Sites. It is designed for egress traffic from specific Kubernetes workloads. For ingress traffic to specific Kubernetes workloads, use the URL access feature (HTTP up action type).


Background information

The injector

You install the Kubernetes injector at the Kubernetes cluster level. You can connect multiple Kubernetes clusters to a single Collective. Set a unique clusterID to avoid resource collisions created by the injector. Each cluster can have multiple namespaces, which in turn have multiple workloads, each comprising one or more pods.

For any given injector installation:

  • You must create a unique clusterID.

  • There is one profile link created for the cluster.

  • Each workload has a unique username and password assigned in the service IdP.

  • Each injected client (sidecar) has a unique deviceID.

The injector handles everything related to the injected headless clients. It sets up credentials, client profiles, and other configurations automatically in the background through API calls to the Controller. The injector must be able to access port 8443 on the Controller—for example, to add a new user identity as headless clients are injected into each pod.

Meta-client

In many cases, the Controller's admin port is not exposed to the internet or access is allowlisted, in line with security best practices. In situations where the injector cannot reach the Controller, an embedded meta-client runs within the injector itself. After you enable and configure the meta-client, it caputres traffic from the injector and tunnels it to the admin API port 8443 on the Controller through a suitably located Gateway. This is separate from the sidecar clients and requires manual configuration.


Installing the k8s client

You install the Kubernetes injector per workload using Helm charts. Browse the latest versions in the AppGate GitHub Container Registry.

This admin guide covers only the aspects that relate to AppGate ZTNA. For the complete setup process, see the readme published in GitHub.


Configuring the k8s client

To use the AppGate Kubernetes injector, configure the following in AppGate ZTNA:

  • API user with required privileges: Create an injector API user (username, password, IdP) and assign an admin policy that includes the admin role with Local User management privileges (use the preset in the admin UI).

  • IP pools: Create an IP pool. One IP address is assigned from the pool for every pod in each Kubernetes workload.

  • Local IdP: Assign the IP pools to the local identity provider.

NOTE

Ten inactive local users are created at the initialization of the Identity Service. They become active users as clients are started, at which point another inactive user is created so there are always 10 available.

  • User License: Obtain and apply a user license. One license is consumed per Kubernetes workload—for example, per Deployment. As with the normal client, one user can have any number of devices.

  • Policy and entitlements for the injected client: Create an access policy for each specific Kubernetes workload referencing suitable entitlements.

Namespace annotations and labels are injected with each client instance and appear as device claims, which you can use for policy assignment decisions. Although these are technically device claims—which are normally considered untrusted—in this specific case they appear as user claims and you can treat them as trusted. You can use the following in policy assignment criteria:

  • Identity provider is local

  • user.labels.namespace (namespace = name of the namespace)

  • user.labels.name (name = label name)

NOTE

JavaScript syntax is required because the format of the labels returned is not defined.

  • Meta-client (optional): The standard client credentials—username, password, and profile link—are required. These may be the same as above.

  • Policy and entitlements for the meta-client (optional): Create an access policy for the meta-client with entitlements that allow access to port 8443 on the Controller and to the DNS server.


Using the client

The client runs for as long as the pod exists. When the pod is destroyed, the client is also destroyed.


Updating the client

The injector uses a fixed version of the client—the latest version at the time the injector was released. To use a different version, add or edit the following line in the deployment YAML file:

k8s.appgate.com/sdp-injector.client-version: 6.7.3


Logs

View logs for the meta-client and the injected headless client by downloading them from Active Sessions (Usage > Active Sessions).