Skip to content

kcp front-proxy

The kcp front-proxy can be used to provide access to either a whole or a subset of a kcp installation. Its main purpose is to act as a gateway, since it builds up a runtime map of all existing workspaces across all shards that it targets, so it knows where to route a request to /clusters/root:my-team to the shard where the logicalcluster for that workspace resides.

Warning

Currently it is required to have at least one front-proxy in a kcp installation, which must be reachable at the hostname also configured as the external name for the root shard. Without a front-proxy, new workspaces will not be able to be scheduled.

The front-proxy must exist even if there is only one shard (the RootShard). This is a requirement of kcp, not the operator itself.

Usage

As mentioned above, your first front-proxy should have the same external hostname as is configured on the root shard. Every additional front-proxy can be served at arbitrary hostnames. Since the CA used to generate the serving certs for front-proxies is embedded in kubeconfigs generated by the kcp-operator, there is no need to use well-known CAs or ACME providers like Let's Encrypt, unless you intend to also access kcp from systems that do not use kubeconfig files and have no way to configure additional CAs.

Mode of Operation

The kcp front-proxy will build up a runtime map of all shards, workspaces and logicalclusters in a kcp installation. For this it connects dynamically to each shard individually and begins to watch the necessary resources. This runtime index is then used to route incoming requests to their target shards.

The proxy can optionally perform authentication, for example using OIDC, and pass authentication information (like username and groups) on to the shard (via HTTP headers). This can be configured for each front-proxy individually. If no authentication is performed, the requests will be passed unauthenticated to their target shards, where then authentication happens.

RootShard Proxy

The kcp-operator will deploy an internal front-proxy for every RootShard (i.e. one for each kcp installation). This internal proxy is solely used by the operator itself to allow it to resolve workspace paths to logicalclusters and provision resources inside those workspaces.

The reason a standalone proxy is deployed is that the admin-configured front-proxies (based on FrontProxy objects) can be configured to drop sensitive groups, like system:masters, from incoming requests. This is a security measure, ensuring no super admin access is possible to kcp from the outside.