You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: pages/getting-started/advanced-config/sandboxing.md
+94-31Lines changed: 94 additions & 31 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -38,27 +38,6 @@ To set it up, you need to configure a few env vars as well, in particular:
38
38
39
39
To simplify permission management, you can also configure specific emails to automatically be made admins via another env var: `CONSOLE_ADMIN_EMAILS`. It should be a comma seperated list, and on login we'll provision that user to be an admin w/in your Plural console instance. We'd recommend only setting this for a small set of users, then using group bindings for permissions from then on
40
40
41
-
## Self-Host Git Repos
42
-
43
-
If your enterprise cannot accept external communication to github, we can provide a fully self-hosted git server built with [soft-serve](https://github.com/charmbracelet/soft-serve) with the required Plural repos pre-cloned at a compatible version for your instance of the console. This can be easily enabled via helm with the following values:
44
-
45
-
```yaml
46
-
extraEnv:
47
-
- name: CONSOLE_DEPLOY_OPERATOR_URL
48
-
value: http://git-server.plrl-console:23232/deployment-operator.git # uses the git server for deployment operator updates
49
-
- name: CONSOLE_ARITIFACTS_URL
50
-
value: http://git-server.plrl-console:23232/scaffolds.git # uses the git server for our default service catalog setup artifacts
51
-
gitServer:
52
-
enabled: true
53
-
```
54
-
55
-
We publish a new version of this every release so you will simply need to ensure it's vendored and ready to pull on each helm upgrade. Many organizations have a natural way to vendor docker images, and since this is deployed as a fully self-contained container image, you can simply repurpose that process to managing the necessary git repositories as well.
56
-
57
-
If you want to vendor the repositories entirely, the upstream repos are here:
58
-
59
-
- https://github.com/pluralsh/deployment-operator
60
-
- https://github.com/pluralsh/scaffolds
61
-
62
41
## Sandboxed Compatibility Tables
63
42
64
43
We also bundle the compatibility and deprecation data in our docker images, and you can disable live polling github by setting the env var:
@@ -73,21 +52,70 @@ This is a suitable replacement if you're ok with some data staleness and don't h
73
52
74
53
Lots of enterprises have strict requirements around the docker registries they use, or pull caches that whitelist a limited set of registries. The important images for setting up your own instance are:
75
54
76
-
- ghcr.io/pluralsh/console
77
-
- ghcr.io/pluralsh/kas
78
-
- ghcr.io/pluralsh/deployment-controller
79
-
- ghcr.io/pluralsh/deployment-operator
55
+
Plural maintained images:
56
+
57
+
```
58
+
Management Cluster:
59
+
- ghcr.io/pluralsh/console
60
+
- ghcr.io/pluralsh/kas
61
+
- ghcr.io/pluralsh/deployment-controller
62
+
- ghcr.io/pluralsh/git-server (optional if you want to use our vendored git server)
63
+
```
64
+
65
+
```
66
+
Agent:
80
67
- ghcr.io/pluralsh/agentk
81
-
- ghcr.io/pluralsh/git-server (optional if you want to use our vendored git server)
68
+
- ghcr.io/pluralsh/deployment-operator
69
+
```
70
+
71
+
```
72
+
Third party images used by our chart (these are often already vendored in an enterprise environment):
If you plan to utilize Stacks, Sentinels or our async coding agent harness, there are a few other images that are utilized by our deployment-operator:
91
+
92
+
```
93
+
- ghcr.io/pluralsh/harness
94
+
- ghcr.io/pluralsh/sentinel-harness
95
+
- ghcr.io/pluralsh/agent-harness
96
+
```
97
+
98
+
You can see them all [here](https://github.com/orgs/pluralsh/packages?repo_name=deployment-operator).
99
+
100
+
The product experience of all these allow bring-your-own image, but if you configure a pull-through cache for these images or vendor them consistently, you can have Plural auto-wire it against an internal registry with the following CRD:
101
+
102
+
```yaml
103
+
apiVersion: deployments.plural.sh/v1alpha1
104
+
kind: AgentConfiguration
105
+
metadata:
106
+
name: global
107
+
namespace: plrl-deploy-operator
108
+
spec:
109
+
baseRegistryURL: your.enterprise.registry
110
+
```
111
+
112
+
See more about this resource [here](/overview/agent-api-reference#agentconfigurationspec)
83
113
84
114
{% callout severity="info" %}
85
115
All of these images follow semver, and are also published to `gcr.io` and `docker.io` as well for convenience, in the event that either of those are eligible for internal pull-through caches. The redis instance is not meaningfully customized and any bitnami or equivalent redis container image can theoretically work there.
86
116
{% /callout %}
87
117
88
-
The first three will be configured in the main console chart and are installed once in your management cluster, the latter two are needed for your deployment agent pod, and require a bit more advanced configuration to manage them in bulk.
89
-
90
-
A starter values file for configuring images for your console in the management cluster would be:
118
+
To configure your *management cluster* helm values, use the following template:
For more advanced configuration, we definitely recommend consulting the charts directly, they're both open source at https://github.com/pluralsh/console and https://github.com/pluralsh/deployment-operator.
122
163
164
+
165
+
## Self-Host Git Repos
166
+
167
+
If your enterprise cannot accept external communication to github, we can provide a fully self-hosted git server built with [soft-serve](https://github.com/charmbracelet/soft-serve) with the required Plural repos pre-cloned at a compatible version for your instance of the console. This can be easily enabled via helm with the following values:
168
+
169
+
```yaml
170
+
extraEnv:
171
+
- name: CONSOLE_DEPLOY_OPERATOR_URL
172
+
value: http://git-server.plrl-console:23232/deployment-operator.git # uses the git server for deployment operator updates
173
+
- name: CONSOLE_ARITIFACTS_URL
174
+
value: http://git-server.plrl-console:23232/scaffolds.git # uses the git server for our default service catalog setup artifacts
175
+
gitServer:
176
+
enabled: true
177
+
```
178
+
179
+
We publish a new version of this every release so you will simply need to ensure it's vendored and ready to pull on each helm upgrade. Many organizations have a natural way to vendor docker images, and since this is deployed as a fully self-contained container image, you can simply repurpose that process to managing the necessary git repositories as well.
180
+
181
+
If you want to vendor the repositories entirely, the upstream repos are here:
182
+
183
+
- https://github.com/pluralsh/deployment-operator
184
+
- https://github.com/pluralsh/scaffolds
185
+
123
186
## Disable cert-manager based TLS
124
187
125
188
Our chart defaults to including TLS reconciled by cert-manager, but if you use a cloud-integrated cert management tool like Amazon Certificate Manager, it is unnecessary and could cause double-encryption. Disabling is a simple values override, done with:
@@ -139,7 +202,7 @@ kas:
139
202
140
203
## Configuring Agent Helm Values
141
204
142
-
Like we said, the main console deployment is pretty easy to configure, but the agents need to be handled specially since they need to be configured in bulk. We provide a number of utilities to make reconfiguration scalable.
205
+
Agents configuration must to be handled specially since they need to be configured in bulk. We provide a number of utilities to make reconfiguration scalable.
143
206
144
207
First, you'll first want to use our agent settings to configure your helm updates for agents globally, done at `/cd/settings/agents`. You should see a screen like the following that allows you to edit the helm values for agent charts managed through Plural:
description: How To Add An Existing Cluster to Your Plural Instance
4
+
---
5
+
6
+
Adding a new cluster to Plural is very simple, it's simply a matter of installing our agent onto any end cluster, and usually follows two paths:
7
+
8
+
1. Leverage our CLI which wraps a full install including registering with your Plural api and helm installing the agent on the cluster
9
+
2. Use our terraform provider to wrap this whole process as Infrastructure as Code
10
+
11
+
Both are functional and fully supported, and execute equivalent code under the hood. If you set up your install with `plural up` we've already wrapped a ton of fully functional GitOps workflows for you, and those usually are more featureful workflows than doing this manually. If you want to read more about them, feel free to look at the guide here: [Create a Workload Cluster](/getting-started/how-to-use/workload-cluster).
12
+
13
+
{% callout severity="info" %}
14
+
We strongly recommend leveraging a IaC based pattern, since it'll allow you to export terraform state into Plural for re-use and maximizes reproducibility
15
+
{% /callout %}
16
+
17
+
18
+
## Onboard a cluster with our CLI
19
+
20
+
To add a new cluster simply run with a valid kubeconfig set up locally:
21
+
22
+
```sh
23
+
plural cd clusters bootstrap --name {your-cluster-name} --tag {tag}={value} --tag {tag2}={value2}
24
+
```
25
+
26
+
To see all CLI options, feel free to use:
27
+
28
+
```sh
29
+
plural cd clusters bootstrap --help
30
+
```
31
+
32
+
If you need to reinstall our agent for any reason, just use:
33
+
34
+
```sh
35
+
plural cd clusters reinstall @{cluster-handle}
36
+
```
37
+
38
+
{% callout severity="info" %}
39
+
The `@` character is required, as it allows our CLI to differentiate names from IDs.
40
+
41
+
You should also address the cluster by handle in the event name is not unique in your system.
42
+
{% /callout %}
43
+
44
+
## Onboard a cluster with our Terraform Provider
45
+
46
+
Here is a basic terraform snippet that shows how you can use our Terraform provider to install our agent
47
+
48
+
```terraform
49
+
resource "plural_cluster" "this" {
50
+
handle = var.cluster
51
+
name = var.cluster
52
+
tags = {
53
+
fleet = var.fleet
54
+
tier = var.tier
55
+
}
56
+
57
+
# metadata attaching useful cluster-level state in Plural to use for service templating
This makes it easy to wrap Plural setup in existing IaC codebases and ensure full repeatability.
91
+
92
+
The metadata block is of importance as well, as it drives our helm + yaml templating experience within Plural CD. You can see some guides around that [here](/plural-features/continuous-deployment/service-templating).
93
+
94
+
## Next Steps
95
+
96
+
Once onboarded, you'll get a few main workflows connected to your cluster:
97
+
98
+
* GitOps Continuous Deployment - learn more [here](/plural-features/continuous-deployment)
99
+
* Kubernetes Dashboarding - learn more [here](/plural-features/kubernetes-dashboard)
100
+
* Plural AI - learn more [here](/plural-features/plural-ai)
101
+
* Plural Flows - learn more [here](/plural-features/flows)
102
+
103
+
If you want a robust, repeatable and scalable way to provision clusters, or other forms of cloud infrastructure, we definitely recommend looking into [Stacks](/plural-features/stacks-iac-management)
104
+
105
+
And if you want everything working out of the box, we'd recommend using `plural up` and going through the [How To Guide](/getting-started/how-to-use) we've constructured which leverages a lot of the GitOps templates that are built into that experience. This covers everything from:
106
+
107
+
1. Kubernetes Fleet Provisioning
108
+
2. Managing a runtime of Kubernetes add-ons
109
+
3. Deploying microservices to k8s and managing them as Flows
0 commit comments