Skip to content

docs: DOC-2359: PCG Reach: Proxy CA Certs #9738

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
achuribooks wants to merge 4 commits into
base: master
Choose a base branch
from
Draft

docs: DOC-2359: PCG Reach: Proxy CA Certs #9738

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f6305ab
docs: DOC-2359: Update PCG reach documentation
achuribooks Mar 4, 2026
4ba0040
Reorganizing information; new page; podmount details
achuribooks Mar 5, 2026
b69fd1f
Validation; additional cleanup
achuribooks Mar 6, 2026
fbe7420
Merge branch 'master' into DOC-2359
achuribooks Mar 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 7 additions & 75 deletions _partials/pcg/_pcg-initial-installation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,88 +54,20 @@ partial_name: pcg-initial-installation

5. If you want to configure your PCG to use a proxy network, complete the following fields, as appropriate.

:::info

By default, proxy environment variables (`HTTPS_PROXY`, `HTTP_PROXY`, and `NO_PROXY`) configured during PCG installation are propagated to all PCG cluster nodes, as well as the nodes of all tenant workload clusters deployed with the PCG. However, proxy CA certificates are only propagated to PCG cluster nodes; they are not propagated the nodes of tenant workload clusters.

:::

| **Parameter** | **Description** |
| :-------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **HTTPS Proxy** | (Optional) Leave blank unless using an HTTPS proxy. This setting propagates to all PCG nodes and all workload cluster nodes deployed using the PCG. Example: `https://<username>:<password>@<proxy-ip>:<proxy-port>`. |
| **HTTP Proxy** | (Optional) Leave blank unless using an HTTP proxy. This setting propagates to all PCG nodes and all workload cluster nodes deployed using the PCG. Example: `http://<username>:<password>@<proxy-ip>:<proxy-port>`. |
| **No Proxy** | (Optional) If using an HTTP or HTTPS proxy, provide a comma-separated list of Classless Inter-Domain Routing (CIDR) addresses, hostnames, and domain names that should bypass the proxy. This setting propagates to all PCG nodes to bypass the proxy server, as well as all workload cluster nodes deployed using the PCG. Example if you have a self-hosted environment: `my.company.com,10.10.0.0/16`. |
| **Proxy CA Certificate Filepath** | (Optional) If using an HTTP or HTTPS proxy, provide the filepath on the installer host to the proxy’s CA certificate file. This certificate is copied to each PCG node during PCG deployment and added to the node trust store. The CA certificate file _must_ be named `ca.crt`. Example: `/usr/local/share/ca-certificates/ca.crt`. <br /><br /> **NOTE**: Proxy CA certificates are _not_ automatically propagated to workload clusters using the PCG; these certificates must be added at either the tenant level or cluster profile OS layer.

<details>

<summary>Configure Proxy CA Certificate for Workload Clusters</summary>

If you are configuring proxy CA certificates for your PCG, they must also be added to workload clusters at the tenant level or cluster profile level in the OS layer.

- If configured at the tenant level, _all_ workload clusters provisioned from the tenant, with the exception of managed Kubernetes clusters (EKS, AKS, and GKE) and Edge clusters, will have the CA certificate injected into their cluster nodes.

- If configured at the cluster profile level, only workload clusters deployed using the cluster profile will be injected with the CA certificate.
<br />
To configure your proxy CA certificate for your workload clusters, use one of the following methods.

<Tabs>

<TabItem value="tenant" label="Tenant Settings">

Take the following approach to propagate your proxy server CA certificate to _all_ workload cluster nodes provisioned from the tenant, with the exception of managed Kubernetes clusters (EKS, AKS, and GKE) and Edge clusters.

1. Log in to [Palette](https://console.spectrocloud.com) as a tenant admin.

2. From the left main menu, select **Tenant Settings**.

3. From the **Tenant Settings Menu**, below **Platform**, select **Certificates**.

4. Select **Add A New Certificate**.

5. In the **Add Certificate** dialog, enter the **Certificate Name** and **Certificate** value.

6. **Confirm** your changes.

</TabItem>

<TabItem value="cluster-profile" label="Cluster Profile OS Layer">

Take the following approach to propagate proxy server CA certificates on a per-cluster basis.

1. Log in to [Palette](https://console.spectrocloud.com).

2. From the left main menu, select **Profiles**.

3. Choose an existing cluster profile or <VersionedLink text="create a new cluster profile" url="/profiles/cluster-profiles/create-cluster-profiles" />. For more information, refer to the <VersionedLink text="cluster profile" url="/profiles/cluster-profiles" /> guide.

4. In the OS layer of your cluster profile, add your CA certificate to the `content` field under `kubeadmconfig.files`. The CA certificate file _must_ be named `ca.crt`.
```yaml hideClipboard title="Example OS layer configuration" {1,10,13-16}
kubeadmconfig:
preKubeadmCommands:
- echo "Executing pre kube admin config commands"
- update-ca-certificates
- 'systemctl restart containerd; sleep 3'
- 'while [ ! -S /var/run/containerd/containerd.sock ]; do echo "Waiting for containerd..."; sleep 1; done'
postKubeadmCommands:
- echo "Executing post kube admin config commands"
files:
- targetPath: /usr/local/share/ca-certificates/ca.crt
targetOwner: "root:root"
targetPermissions: "0644"
content: |
-----BEGIN CERTIFICATE-----
***************************
-----END CERTIFICATE-----
```

5. Select **Confirm Updates**.

</TabItem>

</Tabs>

</details>
:::info

By default, proxy environment variables (`HTTPS_PROXY`, `HTTP_PROXY`, and `NO_PROXY`) configured during PCG installation are propagated to all PCG cluster nodes, as well as the nodes of all workload clusters deployed with the PCG. However, proxy CA certificates are only propagated to PCG cluster nodes; they are not propagated workload cluster nodes. You must configure proxy CA certificates separately at either the tenant level or the cluster profile OS layer. For detailed instructions, including how to mount CA certificates into pods, refer to [Configure Proxy CA Certificates for Workload Clusters](/clusters/pcg/manage-pcg/configure-proxy-ca-certs).

For more information on how PCG environment variables are injected into nodes, refer to our PCG [Architecture](/clusters/pcg/architecture/) page.

:::

6. Enter the following network details.

Expand Down
6 changes: 3 additions & 3 deletions docs/docs-content/architecture/palette-namespaces-pods.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ The following table gives the namespace to pod mapping for Palette Tenant Cluste
| | kube-scheduler-vmdynamictest-cp-< random-hash > | |
| | kube-vip-vmdynamictest-cp-< random-hash > | |
| palette-system | palette-webhook-< random-hash > | Palette webhook that validates and defaults Palette custom resources. May be present depending on the installation type. |
| reach-system | reach-controller-manager-< random-hash > | Reach controller manager responsible for communication between Palette and workload clusters. |
| reach-system | reach-controller-manager-< random-hash > | Reach controller manager that operates as a mutating admission webhook, injecting proxy settings, environment variables, volumes, and volume mounts into matching pods through ClusterPodPreset and PodPreset resources. |
| spectro-task-< random-hash > | crony-< random-hash > | Component responsible for OS upgrades and patching on cluster nodes. |

## Palette PCG NameSpaces with Pods
Expand Down Expand Up @@ -85,8 +85,8 @@ The following table gives the namespace to pod mapping for Palette vSphere Gatew
| | vsphere-csi-controller-< random-hash > | |
| | vsphere-csi-node-< random-hash > | |
| palette-system | palette-webhook-< random-hash > | Palette webhook that validates and defaults Palette custom resources. May be present depending on the installation type. |
| reach-system | reach-controller-manager-< random-hash > | Reach controller manager responsible for communication between Palette and workload clusters. |
| spectro-task-< random-hash > | crony-< random-hash > | Component responsible for OS upgrades and patching on cluster nodes. |
| reach-system | reach-controller-manager-< random-hash > | Reach controller manager that operates as a mutating admission webhook, injecting proxy settings, environment variables, volumes, and volume mounts into matching pods through ClusterPodPreset and PodPreset resources. |
| spectro-task-< random-hash > | crony-< random-hash > | Component responsible for OS upgrades and patching on cluster nodes. |

## Enterprise NameSpaces with Pods

Expand Down
55 changes: 39 additions & 16 deletions docs/docs-content/clusters/pcg/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ tags: ["pcg"]

A Private Cloud Gateway (PCG) facilitates communication between Palette and your infrastructure environment. The PCG is
necessary in environments where Palette does not have direct network access. Many infrastructure environments are placed
in a private network that blocks connections originating externally. The PCG connects to Palette, and acts as an
endpoint, allowing you to target the environment when deploying clusters in Palette.
in a private network that blocks connections that originate from external sources. The PCG connects to Palette and acts
as an endpoint, allowing you to target the environment when deploying clusters in Palette.

When installed, the PCG registers with the self-hosted or SaaS Palette instance you specify, enabling secure
communication between the Palette management plane and the private cloud environment. The PCG enables the deployment and
Expand Down Expand Up @@ -62,28 +62,51 @@ proxy server details are saved as environment variables (`HTTPS_PROXY`, `HTTP_PR
to all PCG cluster nodes, as well as the nodes of all workload clusters deployed with the PCG. The provided proxy
servers are then used by the PCG and workload clusters to access the internet.

You can also provide Certificate Authority (CA) certificates for the proxy server during installation. However, proxy CA
certificates are only propagated to each PCG cluster node; they are not propagated to the nodes of tenant clusters.
You can also provide Certificate Authority (CA) certificates for the proxy server during installation. The certificate
file must be named `ca.crt` and be in PEM format. Proxy CA certificates are only propagated to PCG cluster nodes; they
are not propagated to workload cluster nodes.

Proxy CA certificates must be added to workload clusters at either the tenant level or the cluster profile level in the
OS layer.
OS layer. To make the CA certificate available to pods inside workload clusters, you can use the `podMount`
configuration in the OS layer of your cluster profile. Refer to
[Configure Proxy CA Certificates for Workload Clusters](./manage-pcg/configure-proxy-ca-certs.md) for instructions on
configuring both node-level and pod-level CA certificate trust.

- If configured at the tenant level, _all_ workload clusters provisioned from the tenant, with the exception of managed
Kubernetes clusters (EKS, AKS, and GKE) and Edge clusters, will have the CA certificate injected into their cluster
nodes.

- If configured at the cluster profile level, only workload clusters deployed using the cluster profile will be injected
with the CA certificate.

For guidance on configuring proxy CA certificates, refer to appropriate Palette CLI PCG deployment guide for
[MAAS](./deploy-pcg/maas.md), [OpenStack](./deploy-pcg/openstack.md), [VMware vSphere](./deploy-pcg/vmware.md), or
For guidance on configuring proxy CA certificates during PCG installation, refer to the appropriate Palette CLI PCG
deployment guide for [MAAS](./deploy-pcg/maas.md), [VMware vSphere](./deploy-pcg/vmware.md), or
[Apache CloudStack](./deploy-pcg/cloudstack.md).

#### Existing Kubernetes Cluster

A PCG installed onto an existing Kubernetes cluster will inherit the proxy server configuration from the underlying
Kubernetes cluster. Contact your Kubernetes administrator for the proxy server details and guidance on configuring the
underlying Kubernetes cluster to use a proxy server if needed.
Kubernetes cluster. To configure a proxy on a PCG installed on an existing Kubernetes cluster using the
[Reach system](#reach-system), refer to our [Deploy a PCG to an Existing Kubernetes Cluster](./deploy-pcg-k8s.md) guide.

### Reach System

The Reach system is a Kubernetes
[mutating admission webhook](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/)
that automatically injects configuration into pods at creation time. It is deployed in the `reach-system` namespace on
every Palette CLI-provisioned PCG and can be manually installed on PCGs deployed to an existing Kubernetes cluster. When
deployed, the Reach system creates the following resources:

- **Two Custom Resource Definitions (CRDs)** - _ClusterPodPreset_ (cluster-scoped) and _PodPreset_ (namespace-scoped).
These resources define the environment variables, volumes, and volume mounts to inject into matching pods.

- **MutatingWebhookConfiguration** - Intercepts pod creation requests and applies the preset configurations.

When Palette configures the Reach system with proxy settings, it creates ClusterPodPreset resources that inject the
`HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables into all matching pods across the cluster.
Namespace-scoped PodPreset resources are also created to append namespace-specific entries to the `NO_PROXY` list, so
that in-cluster service discovery traffic bypasses the proxy.

The Reach system also supports injecting volumes and volume mounts into pods. This capability is used to mount
Certificate Authority (CA) certificates into pods so they can trust the proxy server. For more information about
configuring proxy CA certificates for workload clusters, refer to
[Configure Proxy CA Certificates for Workload Clusters](./manage-pcg/configure-proxy-ca-certs.md).

For PCGs deployed to an existing Kubernetes cluster, you must manually install the Reach system using a Helm chart.
Refer to [Enable and Manage Proxy Configurations](./manage-pcg/configure-proxy.md) for instructions.

## Cluster Lifecycle Support

Expand Down
Loading