-
Notifications
You must be signed in to change notification settings - Fork 12
Edge Documentation #620
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.
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
Merged
Merged
Edge Documentation #620
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| --- | ||
| name: documentation-routes | ||
| description: Regenerates documentation route metadata. Use whenever creating, editing, moving, renaming, or deleting documentation content, or when changing the documentation navigation and redirects. | ||
| --- | ||
|
|
||
| # Documentation Routes | ||
|
|
||
| After adding or updating any documentation content, run this command from the documentation repository root: | ||
|
|
||
| ```bash | ||
| make routes | ||
| ``` | ||
|
|
||
| Run it for content-only edits as well as page additions, deletions, moves, navigation changes, and redirect changes. | ||
|
|
||
| Review `generated/routes.json` after the command finishes and include its relevant changes with the documentation update. If route generation fails, fix the failure and rerun `make routes` before completing the task. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
68 changes: 68 additions & 0 deletions
68
pages/getting-started/advanced-config/edge-configuration.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,68 @@ | ||
| --- | ||
| title: Edge configuration | ||
| description: Configure Plural for large edge Kubernetes fleets | ||
| --- | ||
|
|
||
| ## Why Plural works at the edge | ||
|
|
||
| Plural uses a pull-based architecture designed for clusters with restricted or intermittent connectivity. Each workload cluster runs a lightweight deployment agent that initiates connections to the management plane. The management plane does not need inbound network access to the cluster, and deployment credentials remain on the edge device. See the [architecture overview](/overview/architecture) for the complete design. | ||
|
|
||
|  | ||
|
|
||
| The architecture is built for scale: | ||
|
|
||
| * Agent communication is egress-only, so edge devices do not need public endpoints, inbound firewall rules, or a shared private network with the management plane. | ||
| * Plural's [Git-aware caching and distribution layer](/resources/architecture/gitops-architecture) fetches source repositories centrally, creates content-addressed deployment artifacts, and serves them through multiple cache levels. Agents normally fetch a small digest and download an artifact only when its content changes. This avoids multiplying source-control and management-plane traffic by the number of clusters. | ||
| * Plural has been deployed in production environments with more than 5,000 edge clusters. | ||
|
|
||
| For very large fleets, tune the agent to reduce background traffic and persist its caches locally. | ||
|
|
||
| ## Reduce agent polling | ||
|
|
||
| Apply an `AgentConfiguration` named `default` on every edge cluster. The following configuration keeps only service and cluster heartbeat polling enabled, sets both to 20 minutes, disables the persistent websocket, and turns off other periodic agent tasks: | ||
|
|
||
| ```yaml | ||
| apiVersion: deployments.plural.sh/v1alpha1 | ||
| kind: AgentConfiguration | ||
| metadata: | ||
| name: default | ||
| spec: | ||
| servicePollInterval: "20m" | ||
| clusterPingInterval: "20m" | ||
| managedNamespacePollInterval: "0s" | ||
| compatibilityUploadInterval: "20m" | ||
| stackPollInterval: "0s" | ||
| sentinelPollInterval: "0s" | ||
| pipelineGateInterval: "0s" | ||
| vulnerabilityReportUploadInterval: "0s" | ||
| disableWebsocket: true | ||
| ``` | ||
|
|
||
| Setting an interval to `"0s"` disables that task. This profile minimizes requests from each device, but it also disables Stack runs, Sentinel runs, pipeline gate evaluation, vulnerability report uploads, and managed namespace polling on those clusters. We also downtune other polls from their existing defaults, usually 2-3m to support higher scale, this can be toggled up and down based on total fleet, we've found there's usually little need to tune until you get around 1k clusters. | ||
|
|
||
| If an edge cluster needs any of those features, enable its corresponding interval rather than copying this profile unchanged. See [AgentConfiguration](/plural-features/continuous-deployment/deployment-operator/agent-configuration) for the complete field reference and verification steps. | ||
|
|
||
| ## Enable durable agent caches | ||
|
|
||
| Configure the deployment operator chart for the whole fleet through the `DeploymentSettings` resource on the management cluster: | ||
|
|
||
| ```yaml | ||
| apiVersion: deployments.plural.sh/v1alpha1 | ||
| kind: DeploymentSettings | ||
| metadata: | ||
| name: global | ||
| namespace: plrl-deploy-operator | ||
| spec: | ||
| agentHelmValues: | ||
| cache: | ||
| hostPath: | ||
| enabled: true | ||
| ``` | ||
|
|
||
| This mounts a node-local directory into the deployment operator and enables its durable cache. Cached manifests and agent state survive same-node pod restarts and upgrades, reducing cold-start downloads and recomputation on edge devices. | ||
|
|
||
| {% callout severity="warning" %} | ||
| The cache uses node-local `hostPath` storage. It does not follow the pod to another node, so an agent scheduled elsewhere starts with an empty cache. Keep the agent replica count at `1` when `cache.hostPath.enabled` is enabled. | ||
| {% /callout %} | ||
|
|
||
| `DeploymentSettings.spec.agentHelmValues` supplies defaults to agents managed by Plural. Existing agents receive the values during their next agent chart update. See [DeploymentSettings](/plural-features/continuous-deployment/management-controller/deployment-settings#agenthelmvalues) for more details. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.