Clusters Concepts page #1330
Clusters Concepts page #1330
Conversation
ZPain8464
requested review from
calebdoxsey,
wasaga,
desimone,
nhayfield,
ssveta7ak,
kenjenkins and
cmo-pomerium
✅ Deploy Preview for pomerium-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
content/docs/concepts/clusters.mdx
Outdated
|
|
||
| ### Cluster identity | ||
|
|
||
| When you create an account in Pomerium Zero, a new cluster with its own **Cluster Identity** is generated and assigned to your personal account. Pomerium Zero tethers this cluster to your account with the **Pomerium Zero Token** value provided to you during onboarding. |
There was a problem hiding this comment.
A few comments:
-
It feels a little off to say that a cluster is "generated" by Pomerium Zero if we define "cluster" above to mean "a single Pomerium deployment." (That is, the user is the one that sets up a cluster, not Pomerium Zero.)
I think it might be clearer to say that Pomerium Zero generates a "cluster token" which can be used to deploy a new cluster.
-
I'm not sure I understand what "tethers this cluster to your account" means. I'd recommend we replace Cluster Identity and Pomerium Zero Token with just "cluster token".
content/docs/concepts/clusters.mdx
Outdated
|
|
||
| TODO: It would be ideal to get an architecture diagram here. | ||
|
|
||
| ### Cluster identity |
There was a problem hiding this comment.
I'd suggest we standardize on the term "cluster token" for this concept, but open to feedback from others.
content/docs/concepts/clusters.mdx
Outdated
|
|
||
| When you create an account in Pomerium Zero, a new cluster with its own **Cluster Identity** is generated and assigned to your personal account. Pomerium Zero tethers this cluster to your account with the **Pomerium Zero Token** value provided to you during onboarding. | ||
|
|
||
| This cluster identity token acts as a refresh token that you can use to generate a new cluster identity token in the Zero Console (see the [**Rotate cluster identity**](#rotate-cluster-identity) steps below). |
There was a problem hiding this comment.
I don't know that it's helpful to talk about refresh tokens here. You don't really "use" a cluster token when generating a new one — I think it would be more accurate to say something along the lines of "generating a new cluster token invalidates the existing cluster token."
content/docs/concepts/clusters.mdx
Outdated
| <li>Under **Actions**, select the **edit** icon</li> | ||
| <li>Select the **Domains** tab</li> | ||
| <li>In the **Cluster Identity** field, select **Rotate Identity**</li> | ||
| <li>Copy the token and replace the old one in your configuration file</li> |
There was a problem hiding this comment.
I think we'll want to expand on these instructions to include more details specific to the installation type (Linux install script, Kubernetes, Docker Compose).
We may also want to include instructions for how to restart Pomerium after updating the configuration.
content/docs/concepts/clusters.mdx
Outdated
|
|
||
| #### Rotate cluster identity | ||
|
|
||
| A cluster identity token does not have a set expiration time. However, you may want to rotate the cluster identity in the Zero Console for security reasons. After you rotate the cluster identity, the previous token becomes obsolete. |
There was a problem hiding this comment.
I think it's probably worth talking a little more about security.
- What are the risks if a cluster token is exposed?
content/docs/concepts/clusters.mdx
Outdated
|
|
||
| ### Cluster domain | ||
|
|
||
| Pomerium Zero generates and assigns a unique **Cluster Domain** to your cluster. Your cluster domain contains your randomly generated **Cluster Name** and the `pomerium.app` subdomain. |
There was a problem hiding this comment.
Let's think about how we want to talk about this. We might want to use terminology like "starter domain" when referring to the randomly generated domain.
content/docs/concepts/clusters.mdx
Outdated
|
|
||
| #### Change cluster Name | ||
|
|
||
| If you don't like your randomly generated cluster name, you can change it manually in your cluster settings. |
There was a problem hiding this comment.
To me this almost reads like you can change the starter domain by changing the cluster name, which I don't think is the case.
I wonder if this would be a good place to instead link to a guide for adding a custom domain.
| 1. Run `docker compose up -d` | ||
|
|
||
| </TabItem> | ||
| <TabItem value="kubernetes" label="Kubernetes"> |
There was a problem hiding this comment.
Still need to confirm these steps are accurate for K8s.
content/docs/concepts/clusters.mdx
Outdated
|
|
||
|  | ||
|
|
||
| #### Detected and Override IP address |
There was a problem hiding this comment.
I personally think we should include this section here. At a minimum, we should cover these steps in Troubleshooting, or cross-link these pages.
content/docs/concepts/clusters.mdx
Outdated
|
|
||
| ## Clusters overview | ||
|
|
||
| A **Cluster** represents a single Pomerium deployment managed by Pomerium Zero, our hosted control plane. Pomerium Zero enables you to configure cluster settings for your personal account or organization. |
There was a problem hiding this comment.
You can think of a Pomerium cluster as a completely distinct deployment of Pomerium, and allows you to effectively shard you deployments for performance, governance, security, or management purposes.
I think we should probably discuss common reasons people would want to use a cluster.
content/docs/concepts/clusters.mdx
Outdated
|
|
||
| ### Cluster architecture | ||
|
|
||
| TODO: It would be ideal to get an architecture diagram here. |
There was a problem hiding this comment.
An entity diagram would make the relationship more obvious.
|
I could use some input on the "Why clusters" section. It's pretty thin. The other TODOs would be to add a video, clusters architecture, and links for pending pages. |
content/docs/concepts/clusters.mdx
Outdated
|
|
||
| ### Simplified configuration | ||
|
|
||
| Cluster configuration is managed entirely in the Zero Console. As you apply configuration changes in the Zero Console, your cluster fetches and applies these changes locally. |
There was a problem hiding this comment.
I think the intent is to say that this information is managed in Pomerium Zero's control plane correct?
This instead reads like configuration for clusters is managed exclusively in the web ui (which isn' tthe case).
Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>
Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>
Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>
Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>
Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>
Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>
Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>
Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>
Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>
Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>
content/docs/concepts/clusters.mdx
Outdated
|
|
||
| ## Overview | ||
|
|
||
| A **Cluster** represents a single Pomerium deployment managed by Pomerium Zero, our hosted control plane. You can think of a Pomerium cluster as a completely distinct deployment of Pomerium that allows you to effectively shard your deployments for performance, governance, security, or management purposes. | ||
| When you deploy Pomerium Zero, you get your own **Cluster**. A cluster consists of one or more replicas of [Pomerium Core](/docs/deploy/core), the primary server component that secures your services. Clusters are deployed locally and managed through the **Zero Console**, a remote control plane hosted in the Pomerium Zero cloud. |
There was a problem hiding this comment.
I'm not sure if "you deploy Pomerium Zero" is an accurate statement.
There was a problem hiding this comment.
I updated to "install".
content/docs/concepts/clusters.mdx
Outdated
|
|
||
| - A malicious insider could use the token to view the cluster's configuration, which may contain sensitive data | ||
| When you deploy a cluster in Pomerium Zero, a **Cluster Token** is generated for you during onboarding. The cluster token environment variable instructs Pomerium to run in a special "Zero-managed" mode. In Zero-managed mode, your cluster connects to the Pomerium Zero cloud, where you can manage your cluster from the Zero Console. |
There was a problem hiding this comment.
not just "during onboarding"
content/docs/concepts/clusters.mdx
Outdated
| - You may lose track of the existing token, and want a new one | ||
|
|
||
| :::caution | ||
|
|
||
| Rotating the cluster identity will invalidate the existing cluster token. | ||
| Rotating the cluster token will invalidate the current token. |
There was a problem hiding this comment.
| Rotating the cluster token will invalidate the current token. | |
| Rotating the cluster token will invalidate the current token. |
| Rotating the cluster token will invalidate the current token. | |
| Rotating the cluster token will invalidate the current token, and make your cluster shut down. |
content/docs/concepts/clusters.mdx
Outdated
| ### Cluster domain | ||
| ### Detected and Override IP Address | ||
|
|
||
| Whenever you start a cluster, it must fetch its configuration from the Zero Console. During this process, Pomerium attempts to detect the cluster's outbound IP address to connect to it. |
There was a problem hiding this comment.
pomerium core connects to pomerium cloud, thus we do not need to know the IP address for connection purposes.
what I think we need to elaborate is that every cluster gets an automatic domain, and the detected IP address would be set as A or AAAA records for that domain, unless user provided an override value.
content/docs/concepts/clusters.mdx
Outdated
| - Behind a firewall | ||
| - In a Kubernetes server where the ingress load balancer IP address doesn't match the egress IP address | ||
|
|
||
| In such cases, you may see a `DNS_PROBE_FINISHED_NXDOMAIN` error in your browser when you access a route. As a workaround, we've provided the **Override IP Address** field, which allows you to manually set the IP address so that Pomerium Zero can connect to your cluster. |
There was a problem hiding this comment.
the DNS_PROBE_FINISHED_NXDOMAIN error means there's no record available.
it may only show up if we just updated the domain name and changes did not yet propagate to the user's machine, or the cluster was not yet ever connected to the cloud, meaning we do not know the IP address.
the override IP address is indeed required for the cases listed above, but the error in the browser would be different, specifically ERR_CONNECTION_REFUSED - as the cluster is running, but is unreachable using the automatically detected IP address.
content/docs/concepts/clusters.mdx
Outdated
|
|
||
|  | ||
| You can't deploy replicas in the Zero Console itself. To deploy a replica, run the Pomerium Zero installation script using the same [cluster token](#cluster-token) you used to deploy your cluster. This will generate another replica, which you can verify on the [**Status**](https://console.pomerium.app/app/reports/status) page. |
There was a problem hiding this comment.
there seems to be a contradiction in wording: "You can't deploy replicas", followed by "To deploy a replica".
A replica is simply an instance of Pomerium Core deployed on another host.
|
@wasaga if I could get a review sometime this afternoon, that'd be great. |
content/docs/concepts/clusters.mdx
Outdated
|
|
||
| Each replica runs Pomerium Core in an all-in-one mode, meaning the services that comprise Core are deployed together and share session state. Similarly, replicas communicate with each other to synchronize state across a cluster. | ||
|
|
||
| The interconnectivity between replicas enables you to horizontally scale your cluster to adapt to the purposes of your use case, be it performance, governance, security, or management related. |
There was a problem hiding this comment.
I believe the only reason to have multiple replicas is scaling workloads and higher availability. it does not have additional security or management benefits
There was a problem hiding this comment.
I updated the text. Thanks for the in-depth review/s, @wasaga.
This PR adds a Clusters Concepts page, which covers all the relevant details about a cluster that users might want to know.