# Akuity Platform Documentation > Akuity is a fully-managed Kubernetes application delivery platform powered by Argo. The Akuity Platform offers managed Argo CD and Kargo, GitOps tooling, AI-powered observability and remediation through Akuity Intelligence, and a self-hosted deployment option for regulated and air-gapped environments. This file contains all documentation content in a single document following the llmstxt.org standard. ## Akuity Platform Architecture The Akuity Platform automates the deployment of the upstream version of Argo CD, but packages it in a unique hybrid architecture that significantly improves performance and scalability. ## Control Plane vs. Data Plane There are two common approaches to deploying Argo CD: - in a control plane cluster that manages multiple workload clusters. - in each workload cluster. Argo CD in a control plane cluster provides the better experience for developers by serving as a single pane of glass for the whole company infrastructure. However, it requires some security compromises and introduces management and scalability challenges. For an in-depth comparison, see our [*How many do you need? - Argo CD Architectures Explained*](https://akuity.io/blog/argo-cd-architectures-explained/) blog post. One of the unique innovations of the Akuity Platform is that **it separates Argo CD’s data plane from the control plane** and allows to get the best of both worlds. The Akuity Platform hosts and manages the Argo CD frontend - the control plane that enables developers to manage the desired state of their applications and gain visibility into the state of managed infrastructure. The Argo CD Application Controller, however, is running inside of the managed workload clusters and seamlessly connected back to the control plane by the Akuity Agent. ![Akuity Platform Architecture](/img/architecture.png) This separation allows to move the most critical Argo CD component closer to the infrastructure it manages and provides numerous benefits: * **Improved security**. The Argo CD controller is running inside of the managed cluster, so no external cluster access is required. You can leverage the Akuity Platform to manage private clusters without exposing Kubernetes API server. * **Less Management Burden**. No cluster access means no cluster credentials. Administrators no longer need to store and maintain cluster credentials in Argo CD settings and deal with revoked access tokens. * **Improved Scalability**. Higher scalability is achieved by allowing the work of the controller to be distributed and delegated to individual clusters. * **Less Networking Costs**. With the controller running in the managed cluster the heavy Kubernetes resource processing happens in-cluster instead of over the network. Only the relevant pieces of metadata presented in the Argo CD UI are sent over the network. In our real-world testing, this has been shown to reduce traffic consumption by as much as **80%**. To summarize, the Akuity Platform provides a single Argo CD interface for managing infrastructure across many clusters, _without_ the compromises on security or scalability that would typically be required. ## Flexible Architecture Argo CD consists of several components that serve different purposes. The following diagram shows the high-level architecture of Argo CD: ![Argo CD Architecture](/img/argocd_architecture.png) * **API server** - the stateless service that provides the API and UI for Argo CD. * **Application Controller** - the Kubernetes controller that continuously reconciles the state of managed applications and applies changes from Git to managed Kubernetes clusters. * **Application Set** - the controller that automates Argo CD application management. * **Image Updater** - the controller that monitors Docker registries and automatically updates image tags in Git repositories. * **Repo Server** - the service responsible for interacting with Git and generating manifests using config management tools such as [Helm](https://helm.sh/) or [Kustomize](https://kustomize.io/). * **Dex** - the OpenID Connect identity provider used for authentication and authorization. With the unqiue agent-based architecture for Argo CD provided by the Akuity Platform, **the location of the Application Set, Repo Server, and Image Updater components is configurable**. Depending on the use case the desired location of some components varies. For example, some organizations choose to run Repo Server in each cluster, closer to managed workloads. Other organizations prefer to have tighter control over the Git repository and like to run Repo Server in a dedicated cluster with Git access. --- ## Akuity Platform Overview The Akuity Platform is a fully-managed Kubernetes application delivery platform powered by Argo. ## Getting started To get up and running as quickly as possible, checkout the [getting started guide](03-argocd/01-getting-started/10-create-argo-cd-instance.mdx) that will walk you through the fundamentals of the Akuity Platform in just minutes and leave you with a fully operational Argo CD instance. ## What is Argo? Argo is a set of open source tools for Kubernetes to run workflows, manage clusters, and implement the GitOps operational framework. For more info about Argo go to [the Argo Project website](https://argoproj.github.io/). ## Minimum knowledge required To use this documentation and the Akuity Platform effectively, basic familiarity with the following technologies and concepts is suggested: - Containerization ([Docker](https://www.docker.com/), [containerd](https://containerd.io/), etc.) - [Kubernetes](https://kubernetes.io) - Application lifecycle management - [GitOps](https://akuity.io/gitops) - [Argo CD](https://argo-cd.readthedocs.io) ## How to give feedback and get help? If you have any feedback regarding this documentation or the product, please [send us an email](mailto:info@akuity.io). For help please reach out to us through [the contact form on our website](https://akuity.io/connect-with-akuity). --- ## Akuity Platform Networking Requirements ### Egress Traffic Rules - Allow port `443` (TCP) for secure HTTPS and TCP communication. ### Domain Access The following domains need to be configured and allowlisted for access : #### US Region - `akuity.cloud` - `*.cd.akuity.cloud` - `*.cdsvcs.akuity.cloud` - `*.kargo.akuity.cloud` - `*.kargosvcs.akuity.cloud` #### EU Region - `eu.akuity.cloud` - `*.cd.eu.akuity.cloud` - `*.cdsvcs.eu.akuity.cloud` - `*.kargo.eu.akuity.cloud` - `*.kargosvcs.eu.akuity.cloud` ### IP Allowlisting #### Akuity Platform IPs If your workload cluster restricts egress traffic by IP, add the following Akuity Platform addresses to your cluster's allow list so that the Akuity Platform Agent can reach the Akuity Platform: ##### US Region : ``` 35.83.167.172 35.164.149.26 44.227.111.216 13.248.239.50 166.117.206.69 ``` ##### EU Region : ``` 63.180.120.65 3.74.238.191 63.180.42.11 166.117.35.43 99.83.186.100 ``` #### Outbound IPs for External Service Allowlisting When Akuity Platform components _on the controlplane_ (one notable example is when an app-of-apps is used) connects to your external services (such as Git repositories, container registries, or other endpoints), its outbound traffic originates from the following IP addresses. If your external service restricts access by IP — for example, when using [GitHub App IP allow lists](https://docs.github.com/en/organizations/managing-organization-settings/restricting-access-to-your-organizations-ip-allow-list) — add these addresses to permit access: ##### US Region: ``` 52.40.235.49 35.85.123.223 52.32.37.241 ``` ##### EU Region: ``` 63.177.220.72 3.68.60.214 3.120.93.7 ``` #### Cloudflare IPs The Akuity Platform uses Cloudflare as a sub-processor to provide CDN and security services. Cloudflare only processes limited network-level metadata (IP addresses and HTTP request data) and does not access or retain customer application data, credentials, or stored content. Cloudflare is compliant with ISO 27001, SOC 2 Type II, PCI-DSS, GDPR, and other leading security standards. When accessing resources behind IP allowlists (such as private Git repositories or artifact registries), you must add Cloudflare's IP ranges to your allowlist. This ensures that traffic from the Akuity Platform, which routes through Cloudflare, can successfully reach your protected resources. [Cloudflare IP Ranges](https://www.cloudflare.com/ips/) For more information about Akuity's sub-processors, see the [Sub-Processor list](https://trust.akuity.io). --- ## Bring Your Own Key (BYOK) > **Availability:** Enterprise plan add-on — this feature is not included by default with the Enterprise plan. Contact your account team to discuss pricing and enablement. ## Overview By default, Akuity Platform encrypts all sensitive data (cluster credentials, API secrets, notification configurations, and more) at rest using Akuity-managed encryption keys. With **Bring Your Own Key (BYOK)**, you can supply your own encryption key material. Your organization's data will be encrypted exclusively with your key, giving you: - **Key material ownership** — you generate the cryptographic key material used to protect your data - **Org-scoped isolation** — your data is encrypted with a key distinct from other customers - **Key rotation control** — if you ever need to rotate your key, the platform handles re-encryption automatically This is designed for organizations with strict data governance requirements, compliance mandates (SOC 2 Type II, FedRAMP, HIPAA, etc.), or internal policies requiring customer-supplied key material. --- ## How it works 1. **You generate a key** — a 32-byte cryptographically random value, base64-encoded (see below). 2. **You share it with Akuity securely** — send the key to your account team via an approved secure channel (e.g., 1Password share link, encrypted email). Do not send it in plain text over Slack or email. 3. **Akuity provisions the key** — your account team registers it with the platform, scoped to your organization. 4. **All new writes use your key** — from that point forward, any sensitive field written for your organization is encrypted with your key material. 5. **Existing data is migrated** — a background re-encryption job re-encrypts any data previously written with the platform-managed key. --- ## Generating a key Your key must be a **32-byte cryptographically random value**, base64-encoded. Use one of the following methods: **Linux / macOS (openssl):** ```bash openssl rand -base64 32 ``` **Linux / macOS (dd + /dev/urandom):** ```bash dd if=/dev/urandom bs=32 count=1 2>/dev/null | base64 ``` The output will be a 44-character base64 string, for example: ``` 4K1tGHHqhJPYSbMgTnfnUsCaZb9P1w7Fl3Xu8Ae1RJA= ``` **Requirements:** - Exactly 32 bytes of random data (256-bit key) - Base64-encoded - Generated using a cryptographically secure random source — do not use general-purpose random number generators --- ## Key rotation If you need to rotate your encryption key (for example, due to a security incident or internal compliance policy), contact your Akuity account team. Here is how the process works: 1. Generate new key material using the method above. 2. Share it with your Akuity account team via a secure channel. 3. The platform provisions the new key as the active key for your organization. 4. A background re-encryption job migrates existing data to the new key. 5. The old key remains available for decryption until migration completes, then is retired. No downtime is required during rotation. --- ## Requirements and limitations - Available as a **paid add-on** for Enterprise plans only — not included by default. Contact your account team. - Key provisioning is handled by Akuity — you supply the key material, and your account team registers it on your behalf. - Key material must be a 32-byte cryptographically random value, base64-encoded. --- --- ## Private Connectivity (AWS PrivateLink) > **Availability:** Enterprise plan feature, currently available for AWS only. Contact your account team to enable it for your organization. Not available on self-hosted installations. ## Overview By default, your Argo CD and Kargo instances (and the Akuity Agents connected to them) communicate with the Akuity Platform over the public internet, protected by TLS and optional IP allow lists. With **private connectivity**, this traffic flows over [AWS PrivateLink](https://aws.amazon.com/privatelink/) instead: the Akuity Platform exposes a VPC endpoint service, and your VPCs reach it through interface endpoints. Traffic never leaves the AWS network. Private connectivity can be enabled independently for: - The **instance** (the Argo CD or Kargo dashboard and API) - Each **cluster or agent** (the Akuity Agent's connection to the control plane) You can mix both modes — for example, keep the dashboard public while agents in your production VPC connect privately. ## How it works 1. You connect your AWS account to your Akuity organization. The Akuity Platform allow-lists the account on its VPC endpoint service. 1. You create an interface endpoint in your VPC pointing at the Akuity endpoint service, with private DNS enabled. 1. You switch instances, clusters, or agents to Private. They receive private hostnames that resolve to your interface endpoint and are unreachable from the public internet. ## Connecting an AWS account 1. Navigate to Organization Settings → Private Connectivity. 1. Click Add and enter your 12-digit AWS Account ID. 1. Click the info icon next to the account to open its connection details, and note the AWS Service Name for each region — you need it to create the interface endpoint in the next step. :::note An AWS account can be connected to only **one** Akuity organization. If the account is already connected to another organization (including one where it is still pending removal), adding it will fail. ::: ## Creating the interface endpoint In each VPC that needs private connectivity (for example, the VPCs of clusters running the Akuity Agent): 1. Make sure the VPC has both DNS resolution and DNS hostnames enabled — private DNS does not work without them. 1. In the AWS console, go to VPC → Endpoints → Create endpoint. 1. For Service category, select Other endpoint services, enter the AWS Service Name from the connection details, and click Verify service. 1. Select the VPC, then choose one subnet per Availability Zone where your clients (for example, the cluster nodes) run. 1. Keep the IP address type as IPv4. 1. Attach a security group that allows **inbound** TCP `443` from your clients (for example, the VPC or cluster CIDR). Clients connect *to* the endpoint's network interfaces, so an outbound-only rule is not enough. 1. Under Additional settings, enable DNS name (private DNS). This makes the Akuity private hostnames resolve to your interface endpoint inside the VPC. Connections are accepted automatically. Once the endpoint is available, its state appears in the connection details in the dashboard. For a detailed walkthrough of each option, see the AWS documentation on [creating an interface endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html). :::note Create the endpoint in a region the Akuity endpoint service supports (shown in the connection details). Clients in other regions can still use it over VPC peering or Transit Gateway, or you can create a cross-region interface endpoint if your region is listed as supported. ::: ## Enabling private connectivity ### Argo CD or Kargo instance 1. Navigate to Settings → External Access on the instance. 1. Under Private Connectivity, select Private. 1. Click Save. The instance's hostname changes to a private hostname (shown in the dashboard), which only resolves and routes inside VPCs with an interface endpoint. Switching back to Public restores the public hostname. :::note A private instance cannot use a custom domain (FQDN) — the two settings are mutually exclusive. Remove the custom domain before switching to private. ::: ### Clusters and agents Each Argo CD cluster and Kargo agent has its own Private Connectivity setting, available when connecting it or editing it later. Agents switched to Private reach the control plane through your interface endpoint instead of the public internet. To change the default for newly connected agents, use Private Connectivity under the instance's agent default settings. To change many existing agents at once, use the batch update in the agent customization settings. :::note Integration (direct) clusters are agentless and always use public connectivity. Akuity-managed Kargo agents are also always public. ::: ## Disconnecting an AWS account Disconnect an account from Organization Settings → Private Connectivity using the delete action next to it. Disconnecting the **last** account is blocked while any instance, cluster, or agent in the organization still uses private connectivity — the error message lists the affected instances. Switch them to Public first, then disconnect the account. :::caution After the account is removed from the allow list, existing interface endpoints in that account stop working. Delete them on the AWS side to avoid confusion and costs. ::: --- ## Verifying Images Akuity continuously scans its published images for known vulnerabilities (CVEs) and publishes the results of that triage as [OpenVEX](https://openvex.dev/) assessments. VEX ("Vulnerability Exploitability eXchange") records, for each CVE a scanner might flag, whether the image is actually affected — and when it is not, _why_ (for example, the vulnerable code is present in a bundled OS library but is never reachable in an execute path). Folding these assessments into your own scans drops the false positives Akuity has already triaged. The assessments are attached to **each image digest** as a signed [cosign](https://github.com/sigstore/cosign) attestation (keyless, via Sigstore / GitHub OIDC), so they travel with the image — there is no extra endpoint to configure, and the signature proves Akuity authored the assessment for exactly the image you are running. They cover the publicly available Akuity images you run in your own clusters, on **both Akuity Cloud and self-hosted**: - `quay.io/akuity/agent` — the Akuity agent - `quay.io/akuity/argocd` — Akuity's Argo CD build - `ghcr.io/akuity/kargo` — Kargo ## Apply the assessments with Grype Verify and extract the attestation, then pass it to [Grype](https://github.com/anchore/grype) with `--vex`. Verifying first means you only apply assessments whose Akuity signature checks out: ```bash IMAGE=quay.io/akuity/agent: # or quay.io/akuity/argocd, ghcr.io/akuity/kargo # Verify Akuity's signature and extract the OpenVEX document in one step. # A digest may carry more than one attestation (assessments are appended as # dispositions change), so take the most recent by timestamp. cosign verify-attestation --type openvex \ --certificate-oidc-issuer https://token.actions.githubusercontent.com \ --certificate-identity https://github.com/akuityio/cve-triage/.github/workflows/attest-vex.yml@refs/heads/main \ "$IMAGE" \ | jq -s 'map(.payload | @base64d | fromjson | .predicate) | max_by(.timestamp)' > akuity-vex.json # Scan, applying the assessments. CVEs Akuity has marked not_affected are # suppressed (Grype lists them under its ignored set with vex-status # not_affected) and annotated with the justification. grype "$IMAGE" --vex akuity-vex.json ``` A CVE is suppressed only when Akuity has dispositioned it **and** your scanner still reports it — assessments are added as CVEs are triaged, so a freshly built image may surface findings that are not yet dispositioned. ## Verify provenance only To simply confirm that an image carries an authentic Akuity assessment (for example, as a release gate), run the `verify-attestation` step on its own; it exits non-zero if the signature or signer identity does not match: ```bash cosign verify-attestation --type openvex \ --certificate-oidc-issuer https://token.actions.githubusercontent.com \ --certificate-identity https://github.com/akuityio/cve-triage/.github/workflows/attest-vex.yml@refs/heads/main \ quay.io/akuity/argocd: ``` :::info Scope of the assessments Akuity attaches an assessment to the **latest patch of each supported release line**. An assessment pertains to that specific digest; older patches keep the assessment they received while they were current. Suppression is keyed to the exact package versions present in the image, so an assessment authored for one patch will not mis-apply to an image built from different package versions. The attestation is signed by Akuity's vulnerability-triage workflow, a distinct identity from the workflow that builds and signs each release image. ::: --- ## Argo CD Security-Hardened Images ### Security Scan 2026-08-10 Argo CD security-hardened images include precisely what is needed to run Argo CD. As a result, we build smaller-sized images with a reduced number of CVEs. By not including a package manager and inserting the needed runtime dependencies, the attack surface is significantly reduced. Below you will find the weekly-updated security scans of Akuity's security-hardened Argo CD images compared with the open source images. --- ## Akuity v2.14.21-distroless vs Argo CD v2.14.21 [Full list of open source Argo CD vulnerabilities in this release](https://argo-cd.readthedocs.io/en/latest/snyk/v2.14.21/quay.io_argoproj_argocd_v2.14.21.html) quay.io/akuity/argocd:v2.14.21-distroless Vulnerabilities (34) The below table displays CRITICAL and HIGH severence vulnerabilities only Package ID Severity Installed Version Fixed Version busybox CVE-2023-39810 HIGH 1.37.0-r50 1.37.0-r58 busybox CVE-2026-26157 HIGH 1.37.0-r50 1.37.0-r58 busybox CVE-2026-26158 HIGH 1.37.0-r50 1.37.0-r58 git-lfs CVE-2025-68121 CRITICAL 3.7.1-r0 3.7.1-r4 git-lfs CVE-2025-61726 HIGH 3.7.1-r0 3.7.1-r3 git-lfs CVE-2025-61731 HIGH 3.7.1-r0 3.7.1-r3 git-lfs CVE-2025-61732 HIGH 3.7.1-r0 3.7.1-r4 git-lfs CVE-2026-27140 HIGH 3.7.1-r0 3.7.1-r14 git-lfs CVE-2026-32280 HIGH 3.7.1-r0 3.7.1-r14 git-lfs CVE-2026-32281 HIGH 3.7.1-r0 3.7.1-r14 git-lfs CVE-2026-32283 HIGH 3.7.1-r0 3.7.1-r14 git-lfs CVE-2026-33814 HIGH 3.7.1-r0 3.7.1-r12 git-lfs CVE-2026-56852 HIGH 3.7.1-r0 3.7.1-r18 libcrypto3 CVE-2026-31789 CRITICAL 3.6.0-r3 3.6.2-r0 libcrypto3 CVE-2025-15467 HIGH 3.6.0-r3 3.6.1-r0 libcrypto3 CVE-2025-69421 HIGH 3.6.0-r3 3.6.1-r0 libcrypto3 CVE-2026-28386 HIGH 3.6.0-r3 3.6.2-r0 libcrypto3 CVE-2026-28387 HIGH 3.6.0-r3 3.6.2-r0 libcrypto3 CVE-2026-28388 HIGH 3.6.0-r3 3.6.2-r0 libcrypto3 CVE-2026-28389 HIGH 3.6.0-r3 3.6.2-r0 libcrypto3 CVE-2026-28390 HIGH 3.6.0-r3 3.6.2-r0 libcrypto3 CVE-2026-45447 HIGH 3.6.0-r3 3.6.3-r0 libexpat1 CVE-2026-25210 HIGH 2.7.3-r0 2.7.4-r0 libexpat1 CVE-2026-45186 HIGH 2.7.3-r0 2.8.1-r0 libexpat1 CVE-2026-56408 HIGH 2.7.3-r0 2.8.2-r0 libssl3 CVE-2026-31789 CRITICAL 3.6.0-r3 3.6.2-r0 libssl3 CVE-2025-15467 HIGH 3.6.0-r3 3.6.1-r0 libssl3 CVE-2025-69421 HIGH 3.6.0-r3 3.6.1-r0 libssl3 CVE-2026-28386 HIGH 3.6.0-r3 3.6.2-r0 libssl3 CVE-2026-28387 HIGH 3.6.0-r3 3.6.2-r0 libssl3 CVE-2026-28388 HIGH 3.6.0-r3 3.6.2-r0 libssl3 CVE-2026-28389 HIGH 3.6.0-r3 3.6.2-r0 libssl3 CVE-2026-28390 HIGH 3.6.0-r3 3.6.2-r0 libssl3 CVE-2026-45447 HIGH 3.6.0-r3 3.6.3-r0 usr/local/bin/argocd Vulnerabilities (44) The below table displays CRITICAL and HIGH severence vulnerabilities only Package ID Severity Installed Version Fixed Version github.com/argoproj/argo-cd/v2 CVE-2026-45738 HIGH 2.14.21 github.com/expr-lang/expr CVE-2025-68156 HIGH v1.17.0 1.17.7 github.com/go-git/go-billy/v5 CVE-2026-44973 HIGH v5.6.2 5.9.0 github.com/go-git/go-git/v5 CVE-2026-45022 HIGH v5.13.2 5.19.0 github.com/go-git/go-git/v5 CVE-2026-71556 HIGH v5.13.2 5.19.2 github.com/go-jose/go-jose/v4 CVE-2026-34986 HIGH v4.0.2 4.1.4 github.com/moby/spdystream CVE-2026-35469 HIGH v0.4.0 0.5.1 go.opentelemetry.io/otel/sdk CVE-2026-24051 HIGH v1.33.0 1.40.0 go.opentelemetry.io/otel/sdk CVE-2026-39883 HIGH v1.33.0 1.43.0 golang.org/x/crypto CVE-2025-47913 HIGH v0.37.0 0.43.0 golang.org/x/crypto CVE-2026-39828 HIGH v0.37.0 0.52.0 golang.org/x/crypto CVE-2026-39829 HIGH v0.37.0 0.52.0 golang.org/x/crypto CVE-2026-39830 HIGH v0.37.0 0.52.0 golang.org/x/crypto CVE-2026-39831 HIGH v0.37.0 0.52.0 golang.org/x/crypto CVE-2026-39832 HIGH v0.37.0 0.52.0 golang.org/x/crypto CVE-2026-39835 HIGH v0.37.0 0.52.0 golang.org/x/crypto CVE-2026-42508 HIGH v0.37.0 0.52.0 golang.org/x/crypto CVE-2026-46595 HIGH v0.37.0 0.52.0 golang.org/x/crypto CVE-2026-46597 HIGH v0.37.0 0.52.0 golang.org/x/net CVE-2026-25681 HIGH v0.39.0 0.55.0 golang.org/x/net CVE-2026-27136 HIGH v0.39.0 0.55.0 golang.org/x/net CVE-2026-33814 HIGH v0.39.0 0.53.0 golang.org/x/net CVE-2026-39821 HIGH v0.39.0 0.55.0 golang.org/x/oauth2 CVE-2025-22868 HIGH v0.24.0 0.27.0 golang.org/x/text CVE-2026-56852 HIGH v0.24.0 0.39.0 google.golang.org/grpc CVE-2026-33186 CRITICAL v1.68.1 1.79.3 google.golang.org/grpc GHSA-hrxh-6v49-42gf HIGH v1.68.1 1.82.1 oras.land/oras-go/v2 CVE-2026-50151 HIGH v2.5.0 2.6.1 oras.land/oras-go/v2 CVE-2026-50163 HIGH v2.5.0 2.6.2 stdlib CVE-2025-68121 CRITICAL v1.24.6 1.24.13, 1.25.7, 1.26.0-rc.3 stdlib CVE-2025-61726 HIGH v1.24.6 1.24.12, 1.25.6 stdlib CVE-2025-61729 HIGH v1.24.6 1.24.11, 1.25.5 stdlib CVE-2026-25679 HIGH v1.24.6 1.25.8, 1.26.1 stdlib CVE-2026-27145 HIGH v1.24.6 1.25.11, 1.26.4 stdlib CVE-2026-32280 HIGH v1.24.6 1.25.9, 1.26.2 stdlib CVE-2026-32281 HIGH v1.24.6 1.25.9, 1.26.2 stdlib CVE-2026-32283 HIGH v1.24.6 1.25.9, 1.26.2 stdlib CVE-2026-33811 HIGH v1.24.6 1.25.10, 1.26.3 stdlib CVE-2026-33814 HIGH v1.24.6 1.25.10, 1.26.3 stdlib CVE-2026-39820 HIGH v1.24.6 1.25.10, 1.26.3 stdlib CVE-2026-39822 HIGH v1.24.6 1.25.12, 1.26.5, 1.27.0-rc.2 stdlib CVE-2026-39836 HIGH v1.24.6 1.25.10, 1.26.3 stdlib CVE-2026-42499 HIGH v1.24.6 1.25.10, 1.26.3 stdlib CVE-2026-42504 HIGH v1.24.6 1.25.11, 1.26.4 usr/local/bin/gpg-wrapper.sh Vulnerabilities (16) The below table displays CRITICAL and HIGH severence vulnerabilities only Package ID Severity Installed Version Fixed Version stdlib CVE-2025-68121 CRITICAL v1.21.13 1.24.13, 1.25.7, 1.26.0-rc.3 stdlib CVE-2024-34156 HIGH v1.21.13 1.22.7, 1.23.1 stdlib CVE-2025-61726 HIGH v1.21.13 1.24.12, 1.25.6 stdlib CVE-2025-61729 HIGH v1.21.13 1.24.11, 1.25.5 stdlib CVE-2026-25679 HIGH v1.21.13 1.25.8, 1.26.1 stdlib CVE-2026-27145 HIGH v1.21.13 1.25.11, 1.26.4 stdlib CVE-2026-32280 HIGH v1.21.13 1.25.9, 1.26.2 stdlib CVE-2026-32281 HIGH v1.21.13 1.25.9, 1.26.2 stdlib CVE-2026-32283 HIGH v1.21.13 1.25.9, 1.26.2 stdlib CVE-2026-33811 HIGH v1.21.13 1.25.10, 1.26.3 stdlib CVE-2026-33814 HIGH v1.21.13 1.25.10, 1.26.3 stdlib CVE-2026-39820 HIGH v1.21.13 1.25.10, 1.26.3 stdlib CVE-2026-39822 HIGH v1.21.13 1.25.12, 1.26.5, 1.27.0-rc.2 stdlib CVE-2026-39836 HIGH v1.21.13 1.25.10, 1.26.3 stdlib CVE-2026-42499 HIGH v1.21.13 1.25.10, 1.26.3 stdlib CVE-2026-42504 HIGH v1.21.13 1.25.11, 1.26.4 usr/local/bin/helm Vulnerabilities (43) The below table displays CRITICAL and HIGH severence vulnerabilities only Package ID Severity Installed Version Fixed Version github.com/containerd/containerd CVE-2024-25621 HIGH v1.7.23 1.7.29 github.com/containerd/containerd CVE-2026-53488 HIGH v1.7.23 1.7.33 github.com/docker/cli CVE-2025-15558 HIGH v25.0.1+incompatible 29.2.0 github.com/docker/docker CVE-2026-34040 HIGH v25.0.6+incompatible 29.3.1 github.com/docker/docker CVE-2026-41567 HIGH v25.0.6+incompatible github.com/docker/docker CVE-2026-42306 HIGH v25.0.6+incompatible github.com/moby/spdystream CVE-2026-35469 HIGH v0.4.0 0.5.1 golang.org/x/crypto CVE-2024-45337 HIGH v0.27.0 0.31.0 golang.org/x/crypto CVE-2025-22869 HIGH v0.27.0 0.35.0 golang.org/x/crypto CVE-2025-47913 HIGH v0.27.0 0.43.0 golang.org/x/crypto CVE-2026-39828 HIGH v0.27.0 0.52.0 golang.org/x/crypto CVE-2026-39829 HIGH v0.27.0 0.52.0 golang.org/x/crypto CVE-2026-39830 HIGH v0.27.0 0.52.0 golang.org/x/crypto CVE-2026-39831 HIGH v0.27.0 0.52.0 golang.org/x/crypto CVE-2026-39832 HIGH v0.27.0 0.52.0 golang.org/x/crypto CVE-2026-39835 HIGH v0.27.0 0.52.0 golang.org/x/crypto CVE-2026-42508 HIGH v0.27.0 0.52.0 golang.org/x/crypto CVE-2026-46595 HIGH v0.27.0 0.52.0 golang.org/x/crypto CVE-2026-46597 HIGH v0.27.0 0.52.0 golang.org/x/net CVE-2024-45338 HIGH v0.26.0 0.33.0 golang.org/x/net CVE-2026-25681 HIGH v0.26.0 0.55.0 golang.org/x/net CVE-2026-27136 HIGH v0.26.0 0.55.0 golang.org/x/net CVE-2026-33814 HIGH v0.26.0 0.53.0 golang.org/x/net CVE-2026-39821 HIGH v0.26.0 0.55.0 golang.org/x/oauth2 CVE-2025-22868 HIGH v0.21.0 0.27.0 golang.org/x/text CVE-2026-56852 HIGH v0.18.0 0.39.0 google.golang.org/grpc CVE-2026-33186 CRITICAL v1.65.0 1.79.3 google.golang.org/grpc GHSA-hrxh-6v49-42gf HIGH v1.65.0 1.82.1 stdlib CVE-2025-68121 CRITICAL v1.22.7 1.24.13, 1.25.7, 1.26.0-rc.3 stdlib CVE-2025-61726 HIGH v1.22.7 1.24.12, 1.25.6 stdlib CVE-2025-61729 HIGH v1.22.7 1.24.11, 1.25.5 stdlib CVE-2026-25679 HIGH v1.22.7 1.25.8, 1.26.1 stdlib CVE-2026-27145 HIGH v1.22.7 1.25.11, 1.26.4 stdlib CVE-2026-32280 HIGH v1.22.7 1.25.9, 1.26.2 stdlib CVE-2026-32281 HIGH v1.22.7 1.25.9, 1.26.2 stdlib CVE-2026-32283 HIGH v1.22.7 1.25.9, 1.26.2 stdlib CVE-2026-33811 HIGH v1.22.7 1.25.10, 1.26.3 stdlib CVE-2026-33814 HIGH v1.22.7 1.25.10, 1.26.3 stdlib CVE-2026-39820 HIGH v1.22.7 1.25.10, 1.26.3 stdlib CVE-2026-39822 HIGH v1.22.7 1.25.12, 1.26.5, 1.27.0-rc.2 stdlib CVE-2026-39836 HIGH v1.22.7 1.25.10, 1.26.3 stdlib CVE-2026-42499 HIGH v1.22.7 1.25.10, 1.26.3 stdlib CVE-2026-42504 HIGH v1.22.7 1.25.11, 1.26.4 usr/local/bin/kustomize Vulnerabilities (17) The below table displays CRITICAL and HIGH severence vulnerabilities only Package ID Severity Installed Version Fixed Version golang.org/x/text CVE-2026-56852 HIGH v0.16.0 0.39.0 stdlib CVE-2025-68121 CRITICAL v1.21.12 1.24.13, 1.25.7, 1.26.0-rc.3 stdlib CVE-2024-34156 HIGH v1.21.12 1.22.7, 1.23.1 stdlib CVE-2025-61726 HIGH v1.21.12 1.24.12, 1.25.6 stdlib CVE-2025-61729 HIGH v1.21.12 1.24.11, 1.25.5 stdlib CVE-2026-25679 HIGH v1.21.12 1.25.8, 1.26.1 stdlib CVE-2026-27145 HIGH v1.21.12 1.25.11, 1.26.4 stdlib CVE-2026-32280 HIGH v1.21.12 1.25.9, 1.26.2 stdlib CVE-2026-32281 HIGH v1.21.12 1.25.9, 1.26.2 stdlib CVE-2026-32283 HIGH v1.21.12 1.25.9, 1.26.2 stdlib CVE-2026-33811 HIGH v1.21.12 1.25.10, 1.26.3 stdlib CVE-2026-33814 HIGH v1.21.12 1.25.10, 1.26.3 stdlib CVE-2026-39820 HIGH v1.21.12 1.25.10, 1.26.3 stdlib CVE-2026-39822 HIGH v1.21.12 1.25.12, 1.26.5, 1.27.0-rc.2 stdlib CVE-2026-39836 HIGH v1.21.12 1.25.10, 1.26.3 stdlib CVE-2026-42499 HIGH v1.21.12 1.25.10, 1.26.3 stdlib CVE-2026-42504 HIGH v1.21.12 1.25.11, 1.26.4 --- ## Akuity v2.13.9-distroless vs Argo CD v2.13.9 [Full list of open source Argo CD vulnerabilities in this release](https://argo-cd.readthedocs.io/en/latest/snyk/v2.13.9/quay.io_argoproj_argocd_v2.13.9.html) quay.io/akuity/argocd:v2.13.9-distroless Vulnerabilities (35) The below table displays CRITICAL and HIGH severence vulnerabilities only Package ID Severity Installed Version Fixed Version busybox CVE-2023-39810 HIGH 1.37.0-r50 1.37.0-r58 busybox CVE-2026-26157 HIGH 1.37.0-r50 1.37.0-r58 busybox CVE-2026-26158 HIGH 1.37.0-r50 1.37.0-r58 git-lfs CVE-2025-68121 CRITICAL 3.7.0-r1 3.7.1-r4 git-lfs CVE-2025-61726 HIGH 3.7.0-r1 3.7.1-r3 git-lfs CVE-2025-61731 HIGH 3.7.0-r1 3.7.1-r3 git-lfs CVE-2025-61732 HIGH 3.7.0-r1 3.7.1-r4 git-lfs CVE-2026-27140 HIGH 3.7.0-r1 3.7.1-r14 git-lfs CVE-2026-32280 HIGH 3.7.0-r1 3.7.1-r14 git-lfs CVE-2026-32281 HIGH 3.7.0-r1 3.7.1-r14 git-lfs CVE-2026-32283 HIGH 3.7.0-r1 3.7.1-r14 git-lfs CVE-2026-33814 HIGH 3.7.0-r1 3.7.1-r12 git-lfs CVE-2026-56852 HIGH 3.7.0-r1 3.7.1-r18 libcrypto3 CVE-2026-31789 CRITICAL 3.5.2-r1 3.6.2-r0 libcrypto3 CVE-2025-15467 HIGH 3.5.2-r1 3.6.1-r0 libcrypto3 CVE-2025-69421 HIGH 3.5.2-r1 3.6.1-r0 libcrypto3 CVE-2026-28386 HIGH 3.5.2-r1 3.6.2-r0 libcrypto3 CVE-2026-28387 HIGH 3.5.2-r1 3.6.2-r0 libcrypto3 CVE-2026-28388 HIGH 3.5.2-r1 3.6.2-r0 libcrypto3 CVE-2026-28389 HIGH 3.5.2-r1 3.6.2-r0 libcrypto3 CVE-2026-28390 HIGH 3.5.2-r1 3.6.2-r0 libcrypto3 CVE-2026-45447 HIGH 3.5.2-r1 3.6.3-r0 libexpat1 CVE-2025-59375 HIGH 2.7.1-r3 2.7.2-r0 libexpat1 CVE-2026-25210 HIGH 2.7.1-r3 2.7.4-r0 libexpat1 CVE-2026-45186 HIGH 2.7.1-r3 2.8.1-r0 libexpat1 CVE-2026-56408 HIGH 2.7.1-r3 2.8.2-r0 libssl3 CVE-2026-31789 CRITICAL 3.5.2-r1 3.6.2-r0 libssl3 CVE-2025-15467 HIGH 3.5.2-r1 3.6.1-r0 libssl3 CVE-2025-69421 HIGH 3.5.2-r1 3.6.1-r0 libssl3 CVE-2026-28386 HIGH 3.5.2-r1 3.6.2-r0 libssl3 CVE-2026-28387 HIGH 3.5.2-r1 3.6.2-r0 libssl3 CVE-2026-28388 HIGH 3.5.2-r1 3.6.2-r0 libssl3 CVE-2026-28389 HIGH 3.5.2-r1 3.6.2-r0 libssl3 CVE-2026-28390 HIGH 3.5.2-r1 3.6.2-r0 libssl3 CVE-2026-45447 HIGH 3.5.2-r1 3.6.3-r0 usr/local/bin/argocd Vulnerabilities (49) The below table displays CRITICAL and HIGH severence vulnerabilities only Package ID Severity Installed Version Fixed Version github.com/argoproj/argo-cd/v2 CVE-2025-59531 HIGH 2.13.9 2.14.20 github.com/argoproj/argo-cd/v2 CVE-2025-59537 HIGH 2.13.9 2.14.20 github.com/argoproj/argo-cd/v2 CVE-2025-59538 HIGH 2.13.9 2.14.20 github.com/argoproj/argo-cd/v2 CVE-2026-45738 HIGH 2.13.9 github.com/expr-lang/expr CVE-2025-68156 HIGH v1.17.2 1.17.7 github.com/go-git/go-billy/v5 CVE-2026-44973 HIGH v5.6.1 5.9.0 github.com/go-git/go-git/v5 CVE-2026-45022 HIGH v5.13.1 5.19.0 github.com/go-git/go-git/v5 CVE-2026-71556 HIGH v5.13.1 5.19.2 github.com/go-jose/go-jose/v4 CVE-2026-34986 HIGH v4.0.5 4.1.4 github.com/golang-jwt/jwt CVE-2025-30204 HIGH v3.2.2+incompatible github.com/moby/spdystream CVE-2026-35469 HIGH v0.4.0 0.5.1 go.opentelemetry.io/otel/sdk CVE-2026-24051 HIGH v1.30.0 1.40.0 go.opentelemetry.io/otel/sdk CVE-2026-39883 HIGH v1.30.0 1.43.0 golang.org/x/crypto CVE-2025-22869 HIGH v0.32.0 0.35.0 golang.org/x/crypto CVE-2025-47913 HIGH v0.32.0 0.43.0 golang.org/x/crypto CVE-2026-39828 HIGH v0.32.0 0.52.0 golang.org/x/crypto CVE-2026-39829 HIGH v0.32.0 0.52.0 golang.org/x/crypto CVE-2026-39830 HIGH v0.32.0 0.52.0 golang.org/x/crypto CVE-2026-39831 HIGH v0.32.0 0.52.0 golang.org/x/crypto CVE-2026-39832 HIGH v0.32.0 0.52.0 golang.org/x/crypto CVE-2026-39835 HIGH v0.32.0 0.52.0 golang.org/x/crypto CVE-2026-42508 HIGH v0.32.0 0.52.0 golang.org/x/crypto CVE-2026-46595 HIGH v0.32.0 0.52.0 golang.org/x/crypto CVE-2026-46597 HIGH v0.32.0 0.52.0 golang.org/x/net CVE-2026-25681 HIGH v0.33.0 0.55.0 golang.org/x/net CVE-2026-27136 HIGH v0.33.0 0.55.0 golang.org/x/net CVE-2026-33814 HIGH v0.33.0 0.53.0 golang.org/x/net CVE-2026-39821 HIGH v0.33.0 0.55.0 golang.org/x/oauth2 CVE-2025-22868 HIGH v0.23.0 0.27.0 golang.org/x/text CVE-2026-56852 HIGH v0.21.0 0.39.0 google.golang.org/grpc CVE-2026-33186 CRITICAL v1.66.2 1.79.3 google.golang.org/grpc GHSA-hrxh-6v49-42gf HIGH v1.66.2 1.82.1 oras.land/oras-go/v2 CVE-2026-50151 HIGH v2.5.0 2.6.1 oras.land/oras-go/v2 CVE-2026-50163 HIGH v2.5.0 2.6.2 stdlib CVE-2025-68121 CRITICAL v1.23.1 1.24.13, 1.25.7, 1.26.0-rc.3 stdlib CVE-2025-61726 HIGH v1.23.1 1.24.12, 1.25.6 stdlib CVE-2025-61729 HIGH v1.23.1 1.24.11, 1.25.5 stdlib CVE-2026-25679 HIGH v1.23.1 1.25.8, 1.26.1 stdlib CVE-2026-27145 HIGH v1.23.1 1.25.11, 1.26.4 stdlib CVE-2026-32280 HIGH v1.23.1 1.25.9, 1.26.2 stdlib CVE-2026-32281 HIGH v1.23.1 1.25.9, 1.26.2 stdlib CVE-2026-32283 HIGH v1.23.1 1.25.9, 1.26.2 stdlib CVE-2026-33811 HIGH v1.23.1 1.25.10, 1.26.3 stdlib CVE-2026-33814 HIGH v1.23.1 1.25.10, 1.26.3 stdlib CVE-2026-39820 HIGH v1.23.1 1.25.10, 1.26.3 stdlib CVE-2026-39822 HIGH v1.23.1 1.25.12, 1.26.5, 1.27.0-rc.2 stdlib CVE-2026-39836 HIGH v1.23.1 1.25.10, 1.26.3 stdlib CVE-2026-42499 HIGH v1.23.1 1.25.10, 1.26.3 stdlib CVE-2026-42504 HIGH v1.23.1 1.25.11, 1.26.4 usr/local/bin/gpg-wrapper.sh Vulnerabilities (16) The below table displays CRITICAL and HIGH severence vulnerabilities only Package ID Severity Installed Version Fixed Version stdlib CVE-2025-68121 CRITICAL v1.21.13 1.24.13, 1.25.7, 1.26.0-rc.3 stdlib CVE-2024-34156 HIGH v1.21.13 1.22.7, 1.23.1 stdlib CVE-2025-61726 HIGH v1.21.13 1.24.12, 1.25.6 stdlib CVE-2025-61729 HIGH v1.21.13 1.24.11, 1.25.5 stdlib CVE-2026-25679 HIGH v1.21.13 1.25.8, 1.26.1 stdlib CVE-2026-27145 HIGH v1.21.13 1.25.11, 1.26.4 stdlib CVE-2026-32280 HIGH v1.21.13 1.25.9, 1.26.2 stdlib CVE-2026-32281 HIGH v1.21.13 1.25.9, 1.26.2 stdlib CVE-2026-32283 HIGH v1.21.13 1.25.9, 1.26.2 stdlib CVE-2026-33811 HIGH v1.21.13 1.25.10, 1.26.3 stdlib CVE-2026-33814 HIGH v1.21.13 1.25.10, 1.26.3 stdlib CVE-2026-39820 HIGH v1.21.13 1.25.10, 1.26.3 stdlib CVE-2026-39822 HIGH v1.21.13 1.25.12, 1.26.5, 1.27.0-rc.2 stdlib CVE-2026-39836 HIGH v1.21.13 1.25.10, 1.26.3 stdlib CVE-2026-42499 HIGH v1.21.13 1.25.10, 1.26.3 stdlib CVE-2026-42504 HIGH v1.21.13 1.25.11, 1.26.4 usr/local/bin/helm Vulnerabilities (44) The below table displays CRITICAL and HIGH severence vulnerabilities only Package ID Severity Installed Version Fixed Version github.com/containerd/containerd CVE-2024-25621 HIGH v1.7.12 1.7.29 github.com/containerd/containerd CVE-2026-53488 HIGH v1.7.12 1.7.33 github.com/docker/cli CVE-2025-15558 HIGH v25.0.1+incompatible 29.2.0 github.com/docker/docker CVE-2026-34040 HIGH v25.0.6+incompatible 29.3.1 github.com/docker/docker CVE-2026-41567 HIGH v25.0.6+incompatible github.com/docker/docker CVE-2026-42306 HIGH v25.0.6+incompatible github.com/moby/spdystream CVE-2026-35469 HIGH v0.2.0 0.5.1 golang.org/x/crypto CVE-2024-45337 HIGH v0.25.0 0.31.0 golang.org/x/crypto CVE-2025-22869 HIGH v0.25.0 0.35.0 golang.org/x/crypto CVE-2025-47913 HIGH v0.25.0 0.43.0 golang.org/x/crypto CVE-2026-39828 HIGH v0.25.0 0.52.0 golang.org/x/crypto CVE-2026-39829 HIGH v0.25.0 0.52.0 golang.org/x/crypto CVE-2026-39830 HIGH v0.25.0 0.52.0 golang.org/x/crypto CVE-2026-39831 HIGH v0.25.0 0.52.0 golang.org/x/crypto CVE-2026-39832 HIGH v0.25.0 0.52.0 golang.org/x/crypto CVE-2026-39835 HIGH v0.25.0 0.52.0 golang.org/x/crypto CVE-2026-42508 HIGH v0.25.0 0.52.0 golang.org/x/crypto CVE-2026-46595 HIGH v0.25.0 0.52.0 golang.org/x/crypto CVE-2026-46597 HIGH v0.25.0 0.52.0 golang.org/x/net CVE-2024-45338 HIGH v0.23.0 0.33.0 golang.org/x/net CVE-2026-25681 HIGH v0.23.0 0.55.0 golang.org/x/net CVE-2026-27136 HIGH v0.23.0 0.55.0 golang.org/x/net CVE-2026-33814 HIGH v0.23.0 0.53.0 golang.org/x/net CVE-2026-39821 HIGH v0.23.0 0.55.0 golang.org/x/oauth2 CVE-2025-22868 HIGH v0.10.0 0.27.0 golang.org/x/text CVE-2026-56852 HIGH v0.16.0 0.39.0 google.golang.org/grpc CVE-2026-33186 CRITICAL v1.58.3 1.79.3 google.golang.org/grpc GHSA-hrxh-6v49-42gf HIGH v1.58.3 1.82.1 stdlib CVE-2025-68121 CRITICAL v1.22.6 1.24.13, 1.25.7, 1.26.0-rc.3 stdlib CVE-2024-34156 HIGH v1.22.6 1.22.7, 1.23.1 stdlib CVE-2025-61726 HIGH v1.22.6 1.24.12, 1.25.6 stdlib CVE-2025-61729 HIGH v1.22.6 1.24.11, 1.25.5 stdlib CVE-2026-25679 HIGH v1.22.6 1.25.8, 1.26.1 stdlib CVE-2026-27145 HIGH v1.22.6 1.25.11, 1.26.4 stdlib CVE-2026-32280 HIGH v1.22.6 1.25.9, 1.26.2 stdlib CVE-2026-32281 HIGH v1.22.6 1.25.9, 1.26.2 stdlib CVE-2026-32283 HIGH v1.22.6 1.25.9, 1.26.2 stdlib CVE-2026-33811 HIGH v1.22.6 1.25.10, 1.26.3 stdlib CVE-2026-33814 HIGH v1.22.6 1.25.10, 1.26.3 stdlib CVE-2026-39820 HIGH v1.22.6 1.25.10, 1.26.3 stdlib CVE-2026-39822 HIGH v1.22.6 1.25.12, 1.26.5, 1.27.0-rc.2 stdlib CVE-2026-39836 HIGH v1.22.6 1.25.10, 1.26.3 stdlib CVE-2026-42499 HIGH v1.22.6 1.25.10, 1.26.3 stdlib CVE-2026-42504 HIGH v1.22.6 1.25.11, 1.26.4 usr/local/bin/kustomize Vulnerabilities (17) The below table displays CRITICAL and HIGH severence vulnerabilities only Package ID Severity Installed Version Fixed Version golang.org/x/text CVE-2026-56852 HIGH v0.16.0 0.39.0 stdlib CVE-2025-68121 CRITICAL v1.21.12 1.24.13, 1.25.7, 1.26.0-rc.3 stdlib CVE-2024-34156 HIGH v1.21.12 1.22.7, 1.23.1 stdlib CVE-2025-61726 HIGH v1.21.12 1.24.12, 1.25.6 stdlib CVE-2025-61729 HIGH v1.21.12 1.24.11, 1.25.5 stdlib CVE-2026-25679 HIGH v1.21.12 1.25.8, 1.26.1 stdlib CVE-2026-27145 HIGH v1.21.12 1.25.11, 1.26.4 stdlib CVE-2026-32280 HIGH v1.21.12 1.25.9, 1.26.2 stdlib CVE-2026-32281 HIGH v1.21.12 1.25.9, 1.26.2 stdlib CVE-2026-32283 HIGH v1.21.12 1.25.9, 1.26.2 stdlib CVE-2026-33811 HIGH v1.21.12 1.25.10, 1.26.3 stdlib CVE-2026-33814 HIGH v1.21.12 1.25.10, 1.26.3 stdlib CVE-2026-39820 HIGH v1.21.12 1.25.10, 1.26.3 stdlib CVE-2026-39822 HIGH v1.21.12 1.25.12, 1.26.5, 1.27.0-rc.2 stdlib CVE-2026-39836 HIGH v1.21.12 1.25.10, 1.26.3 stdlib CVE-2026-42499 HIGH v1.21.12 1.25.10, 1.26.3 stdlib CVE-2026-42504 HIGH v1.21.12 1.25.11, 1.26.4 --- ## Akuity v2.12.13-distroless vs Argo CD v2.12.13 [Full list of open source Argo CD vulnerabilities in this release](https://argo-cd.readthedocs.io/en/latest/snyk/v2.12.13/quay.io_argoproj_argocd_v2.12.13.html) quay.io/akuity/argocd:v2.12.13-distroless Vulnerabilities (35) The below table displays CRITICAL and HIGH severence vulnerabilities only Package ID Severity Installed Version Fixed Version busybox CVE-2023-39810 HIGH 1.37.0-r50 1.37.0-r58 busybox CVE-2026-26157 HIGH 1.37.0-r50 1.37.0-r58 busybox CVE-2026-26158 HIGH 1.37.0-r50 1.37.0-r58 git-lfs CVE-2025-68121 CRITICAL 3.7.0-r1 3.7.1-r4 git-lfs CVE-2025-61726 HIGH 3.7.0-r1 3.7.1-r3 git-lfs CVE-2025-61731 HIGH 3.7.0-r1 3.7.1-r3 git-lfs CVE-2025-61732 HIGH 3.7.0-r1 3.7.1-r4 git-lfs CVE-2026-27140 HIGH 3.7.0-r1 3.7.1-r14 git-lfs CVE-2026-32280 HIGH 3.7.0-r1 3.7.1-r14 git-lfs CVE-2026-32281 HIGH 3.7.0-r1 3.7.1-r14 git-lfs CVE-2026-32283 HIGH 3.7.0-r1 3.7.1-r14 git-lfs CVE-2026-33814 HIGH 3.7.0-r1 3.7.1-r12 git-lfs CVE-2026-56852 HIGH 3.7.0-r1 3.7.1-r18 libcrypto3 CVE-2026-31789 CRITICAL 3.5.2-r1 3.6.2-r0 libcrypto3 CVE-2025-15467 HIGH 3.5.2-r1 3.6.1-r0 libcrypto3 CVE-2025-69421 HIGH 3.5.2-r1 3.6.1-r0 libcrypto3 CVE-2026-28386 HIGH 3.5.2-r1 3.6.2-r0 libcrypto3 CVE-2026-28387 HIGH 3.5.2-r1 3.6.2-r0 libcrypto3 CVE-2026-28388 HIGH 3.5.2-r1 3.6.2-r0 libcrypto3 CVE-2026-28389 HIGH 3.5.2-r1 3.6.2-r0 libcrypto3 CVE-2026-28390 HIGH 3.5.2-r1 3.6.2-r0 libcrypto3 CVE-2026-45447 HIGH 3.5.2-r1 3.6.3-r0 libexpat1 CVE-2025-59375 HIGH 2.7.1-r3 2.7.2-r0 libexpat1 CVE-2026-25210 HIGH 2.7.1-r3 2.7.4-r0 libexpat1 CVE-2026-45186 HIGH 2.7.1-r3 2.8.1-r0 libexpat1 CVE-2026-56408 HIGH 2.7.1-r3 2.8.2-r0 libssl3 CVE-2026-31789 CRITICAL 3.5.2-r1 3.6.2-r0 libssl3 CVE-2025-15467 HIGH 3.5.2-r1 3.6.1-r0 libssl3 CVE-2025-69421 HIGH 3.5.2-r1 3.6.1-r0 libssl3 CVE-2026-28386 HIGH 3.5.2-r1 3.6.2-r0 libssl3 CVE-2026-28387 HIGH 3.5.2-r1 3.6.2-r0 libssl3 CVE-2026-28388 HIGH 3.5.2-r1 3.6.2-r0 libssl3 CVE-2026-28389 HIGH 3.5.2-r1 3.6.2-r0 libssl3 CVE-2026-28390 HIGH 3.5.2-r1 3.6.2-r0 libssl3 CVE-2026-45447 HIGH 3.5.2-r1 3.6.3-r0 usr/local/bin/argocd Vulnerabilities (53) The below table displays CRITICAL and HIGH severence vulnerabilities only Package ID Severity Installed Version Fixed Version github.com/argoproj/argo-cd/v2 CVE-2025-47933 CRITICAL 2.12.13 2.13.8, 2.14.13 github.com/argoproj/argo-cd/v2 CVE-2025-59531 HIGH 2.12.13 2.14.20 github.com/argoproj/argo-cd/v2 CVE-2025-59537 HIGH 2.12.13 2.14.20 github.com/argoproj/argo-cd/v2 CVE-2025-59538 HIGH 2.12.13 2.14.20 github.com/argoproj/argo-cd/v2 CVE-2026-45738 HIGH 2.12.13 github.com/expr-lang/expr CVE-2025-68156 HIGH v1.17.2 1.17.7 github.com/go-git/go-billy/v5 CVE-2026-44973 HIGH v5.6.1 5.9.0 github.com/go-git/go-git/v5 CVE-2026-45022 HIGH v5.13.1 5.19.0 github.com/go-git/go-git/v5 CVE-2026-71556 HIGH v5.13.1 5.19.2 github.com/go-jose/go-jose/v3 CVE-2026-34986 HIGH v3.0.3 3.0.5 github.com/golang-jwt/jwt CVE-2025-30204 HIGH v3.2.2+incompatible github.com/moby/spdystream CVE-2026-35469 HIGH v0.2.0 0.5.1 go.opentelemetry.io/otel/sdk CVE-2026-24051 HIGH v1.21.0 1.40.0 go.opentelemetry.io/otel/sdk CVE-2026-39883 HIGH v1.21.0 1.43.0 golang.org/x/crypto CVE-2025-22869 HIGH v0.31.0 0.35.0 golang.org/x/crypto CVE-2025-47913 HIGH v0.31.0 0.43.0 golang.org/x/crypto CVE-2026-39828 HIGH v0.31.0 0.52.0 golang.org/x/crypto CVE-2026-39829 HIGH v0.31.0 0.52.0 golang.org/x/crypto CVE-2026-39830 HIGH v0.31.0 0.52.0 golang.org/x/crypto CVE-2026-39831 HIGH v0.31.0 0.52.0 golang.org/x/crypto CVE-2026-39832 HIGH v0.31.0 0.52.0 golang.org/x/crypto CVE-2026-39835 HIGH v0.31.0 0.52.0 golang.org/x/crypto CVE-2026-42508 HIGH v0.31.0 0.52.0 golang.org/x/crypto CVE-2026-46595 HIGH v0.31.0 0.52.0 golang.org/x/crypto CVE-2026-46597 HIGH v0.31.0 0.52.0 golang.org/x/net CVE-2026-25681 HIGH v0.33.0 0.55.0 golang.org/x/net CVE-2026-27136 HIGH v0.33.0 0.55.0 golang.org/x/net CVE-2026-33814 HIGH v0.33.0 0.53.0 golang.org/x/net CVE-2026-39821 HIGH v0.33.0 0.55.0 golang.org/x/oauth2 CVE-2025-22868 HIGH v0.12.0 0.27.0 golang.org/x/text CVE-2026-56852 HIGH v0.21.0 0.39.0 google.golang.org/grpc CVE-2026-33186 CRITICAL v1.59.0 1.79.3 google.golang.org/grpc GHSA-hrxh-6v49-42gf HIGH v1.59.0 1.82.1 k8s.io/kubernetes CVE-2024-10220 HIGH v1.29.6 1.28.12, 1.29.7, 1.30.3 k8s.io/kubernetes CVE-2024-5321 HIGH v1.29.6 1.27.16, 1.28.12, 1.29.7, 1.30.3 oras.land/oras-go/v2 CVE-2026-50151 HIGH v2.3.0 2.6.1 oras.land/oras-go/v2 CVE-2026-50163 HIGH v2.3.0 2.6.2 stdlib CVE-2025-68121 CRITICAL v1.22.4 1.24.13, 1.25.7, 1.26.0-rc.3 stdlib CVE-2024-34156 HIGH v1.22.4 1.22.7, 1.23.1 stdlib CVE-2025-61726 HIGH v1.22.4 1.24.12, 1.25.6 stdlib CVE-2025-61729 HIGH v1.22.4 1.24.11, 1.25.5 stdlib CVE-2026-25679 HIGH v1.22.4 1.25.8, 1.26.1 stdlib CVE-2026-27145 HIGH v1.22.4 1.25.11, 1.26.4 stdlib CVE-2026-32280 HIGH v1.22.4 1.25.9, 1.26.2 stdlib CVE-2026-32281 HIGH v1.22.4 1.25.9, 1.26.2 stdlib CVE-2026-32283 HIGH v1.22.4 1.25.9, 1.26.2 stdlib CVE-2026-33811 HIGH v1.22.4 1.25.10, 1.26.3 stdlib CVE-2026-33814 HIGH v1.22.4 1.25.10, 1.26.3 stdlib CVE-2026-39820 HIGH v1.22.4 1.25.10, 1.26.3 stdlib CVE-2026-39822 HIGH v1.22.4 1.25.12, 1.26.5, 1.27.0-rc.2 stdlib CVE-2026-39836 HIGH v1.22.4 1.25.10, 1.26.3 stdlib CVE-2026-42499 HIGH v1.22.4 1.25.10, 1.26.3 stdlib CVE-2026-42504 HIGH v1.22.4 1.25.11, 1.26.4 usr/local/bin/gpg-wrapper.sh Vulnerabilities (16) The below table displays CRITICAL and HIGH severence vulnerabilities only Package ID Severity Installed Version Fixed Version stdlib CVE-2025-68121 CRITICAL v1.21.13 1.24.13, 1.25.7, 1.26.0-rc.3 stdlib CVE-2024-34156 HIGH v1.21.13 1.22.7, 1.23.1 stdlib CVE-2025-61726 HIGH v1.21.13 1.24.12, 1.25.6 stdlib CVE-2025-61729 HIGH v1.21.13 1.24.11, 1.25.5 stdlib CVE-2026-25679 HIGH v1.21.13 1.25.8, 1.26.1 stdlib CVE-2026-27145 HIGH v1.21.13 1.25.11, 1.26.4 stdlib CVE-2026-32280 HIGH v1.21.13 1.25.9, 1.26.2 stdlib CVE-2026-32281 HIGH v1.21.13 1.25.9, 1.26.2 stdlib CVE-2026-32283 HIGH v1.21.13 1.25.9, 1.26.2 stdlib CVE-2026-33811 HIGH v1.21.13 1.25.10, 1.26.3 stdlib CVE-2026-33814 HIGH v1.21.13 1.25.10, 1.26.3 stdlib CVE-2026-39820 HIGH v1.21.13 1.25.10, 1.26.3 stdlib CVE-2026-39822 HIGH v1.21.13 1.25.12, 1.26.5, 1.27.0-rc.2 stdlib CVE-2026-39836 HIGH v1.21.13 1.25.10, 1.26.3 stdlib CVE-2026-42499 HIGH v1.21.13 1.25.10, 1.26.3 stdlib CVE-2026-42504 HIGH v1.21.13 1.25.11, 1.26.4 usr/local/bin/helm Vulnerabilities (45) The below table displays CRITICAL and HIGH severence vulnerabilities only Package ID Severity Installed Version Fixed Version github.com/containerd/containerd CVE-2024-25621 HIGH v1.7.12 1.7.29 github.com/containerd/containerd CVE-2026-53488 HIGH v1.7.12 1.7.33 github.com/docker/cli CVE-2025-15558 HIGH v25.0.1+incompatible 29.2.0 github.com/docker/docker CVE-2024-41110 CRITICAL v25.0.5+incompatible 23.0.15, 26.1.5, 27.1.1, 25.0.6 github.com/docker/docker CVE-2026-34040 HIGH v25.0.5+incompatible 29.3.1 github.com/docker/docker CVE-2026-41567 HIGH v25.0.5+incompatible github.com/docker/docker CVE-2026-42306 HIGH v25.0.5+incompatible github.com/moby/spdystream CVE-2026-35469 HIGH v0.2.0 0.5.1 golang.org/x/crypto CVE-2024-45337 HIGH v0.21.0 0.31.0 golang.org/x/crypto CVE-2025-22869 HIGH v0.21.0 0.35.0 golang.org/x/crypto CVE-2025-47913 HIGH v0.21.0 0.43.0 golang.org/x/crypto CVE-2026-39828 HIGH v0.21.0 0.52.0 golang.org/x/crypto CVE-2026-39829 HIGH v0.21.0 0.52.0 golang.org/x/crypto CVE-2026-39830 HIGH v0.21.0 0.52.0 golang.org/x/crypto CVE-2026-39831 HIGH v0.21.0 0.52.0 golang.org/x/crypto CVE-2026-39832 HIGH v0.21.0 0.52.0 golang.org/x/crypto CVE-2026-39835 HIGH v0.21.0 0.52.0 golang.org/x/crypto CVE-2026-42508 HIGH v0.21.0 0.52.0 golang.org/x/crypto CVE-2026-46595 HIGH v0.21.0 0.52.0 golang.org/x/crypto CVE-2026-46597 HIGH v0.21.0 0.52.0 golang.org/x/net CVE-2024-45338 HIGH v0.23.0 0.33.0 golang.org/x/net CVE-2026-25681 HIGH v0.23.0 0.55.0 golang.org/x/net CVE-2026-27136 HIGH v0.23.0 0.55.0 golang.org/x/net CVE-2026-33814 HIGH v0.23.0 0.53.0 golang.org/x/net CVE-2026-39821 HIGH v0.23.0 0.55.0 golang.org/x/oauth2 CVE-2025-22868 HIGH v0.10.0 0.27.0 golang.org/x/text CVE-2026-56852 HIGH v0.14.0 0.39.0 google.golang.org/grpc CVE-2026-33186 CRITICAL v1.58.3 1.79.3 google.golang.org/grpc GHSA-hrxh-6v49-42gf HIGH v1.58.3 1.82.1 stdlib CVE-2025-68121 CRITICAL v1.22.4 1.24.13, 1.25.7, 1.26.0-rc.3 stdlib CVE-2024-34156 HIGH v1.22.4 1.22.7, 1.23.1 stdlib CVE-2025-61726 HIGH v1.22.4 1.24.12, 1.25.6 stdlib CVE-2025-61729 HIGH v1.22.4 1.24.11, 1.25.5 stdlib CVE-2026-25679 HIGH v1.22.4 1.25.8, 1.26.1 stdlib CVE-2026-27145 HIGH v1.22.4 1.25.11, 1.26.4 stdlib CVE-2026-32280 HIGH v1.22.4 1.25.9, 1.26.2 stdlib CVE-2026-32281 HIGH v1.22.4 1.25.9, 1.26.2 stdlib CVE-2026-32283 HIGH v1.22.4 1.25.9, 1.26.2 stdlib CVE-2026-33811 HIGH v1.22.4 1.25.10, 1.26.3 stdlib CVE-2026-33814 HIGH v1.22.4 1.25.10, 1.26.3 stdlib CVE-2026-39820 HIGH v1.22.4 1.25.10, 1.26.3 stdlib CVE-2026-39822 HIGH v1.22.4 1.25.12, 1.26.5, 1.27.0-rc.2 stdlib CVE-2026-39836 HIGH v1.22.4 1.25.10, 1.26.3 stdlib CVE-2026-42499 HIGH v1.22.4 1.25.10, 1.26.3 stdlib CVE-2026-42504 HIGH v1.22.4 1.25.11, 1.26.4 usr/local/bin/kustomize Vulnerabilities (18) The below table displays CRITICAL and HIGH severence vulnerabilities only Package ID Severity Installed Version Fixed Version golang.org/x/text CVE-2026-56852 HIGH v0.14.0 0.39.0 stdlib CVE-2024-24790 CRITICAL v1.21.10 1.21.11, 1.22.4 stdlib CVE-2025-68121 CRITICAL v1.21.10 1.24.13, 1.25.7, 1.26.0-rc.3 stdlib CVE-2024-34156 HIGH v1.21.10 1.22.7, 1.23.1 stdlib CVE-2025-61726 HIGH v1.21.10 1.24.12, 1.25.6 stdlib CVE-2025-61729 HIGH v1.21.10 1.24.11, 1.25.5 stdlib CVE-2026-25679 HIGH v1.21.10 1.25.8, 1.26.1 stdlib CVE-2026-27145 HIGH v1.21.10 1.25.11, 1.26.4 stdlib CVE-2026-32280 HIGH v1.21.10 1.25.9, 1.26.2 stdlib CVE-2026-32281 HIGH v1.21.10 1.25.9, 1.26.2 stdlib CVE-2026-32283 HIGH v1.21.10 1.25.9, 1.26.2 stdlib CVE-2026-33811 HIGH v1.21.10 1.25.10, 1.26.3 stdlib CVE-2026-33814 HIGH v1.21.10 1.25.10, 1.26.3 stdlib CVE-2026-39820 HIGH v1.21.10 1.25.10, 1.26.3 stdlib CVE-2026-39822 HIGH v1.21.10 1.25.12, 1.26.5, 1.27.0-rc.2 stdlib CVE-2026-39836 HIGH v1.21.10 1.25.10, 1.26.3 stdlib CVE-2026-42499 HIGH v1.21.10 1.25.10, 1.26.3 stdlib CVE-2026-42504 HIGH v1.21.10 1.25.11, 1.26.4 --- --- ## Security --- ## Akuity Platform Members ## Inviting a new member 1. Select the Organization you want to invite a new member to from the pull down menu. 2. Switch to the Members tab. 3. Click Invite member button on the lower left side of the page. ![Invite members](/img/invite_org_members.png) 4. Enter one or more Email addresses to invite to the organization. 5. Assign a Role [(Owner, Member)](./index.md#roles) for the invited user. 6. If you choose Member role, you can also assign them to specific [Teams](./60-teams.md) and [Workspaces](./70-workspaces.md) with designated roles. 7. Click the Send button. 8. Invitation emails will be sent to the specified email addresses. ## Managing Members in a Team: You can [Manage members in a Team](./60-teams.md#managing-members-in-a-team). ## Managing Members in a Workspace: You can [Manage members in a Workspace](./70-workspaces.md#managing-users-and-teams-in-workspaces). --- ## Technical Contacts Technical Contacts are the people in your organization who should be notified of critical communications from Akuity, such as security advisories (CVEs), major updates, and platform changes that require action. By designating Technical Contacts, you ensure that important notices reach the right people in your organization, even if they are not the organization owner. :::info The `owner` role on the Organization is required to manage Technical Contacts. Organization members can view the list but cannot edit it. By default, an organization owner's email is set as the initial Technical Contact. ::: ## Managing Technical Contacts To manage Technical Contacts for your organization: 1. Click the Organization drop-down on the left navigation menu and click Settings. 2. Click the Contacts tab. 3. Choose email addresses from your organization members, or type any email address. Distribution list addresses are also supported. 4. Click Update to apply the changes. ![Technical Contacts](/img/akuity_organizations_01.png) :::note An organization must have at least 1 and can have at most 5 Technical Contacts. Keep the list focused on the people who can act on security and platform notices. ::: --- ## Akuity Platform API Keys ## Creating an API Key 1. Select the Organization you want to create a key for, from the pull down menu. 2. Switch to the API Keys tab. 2. Click + New Key button on the lower right side of the page. 3. Enter a Description for the key. 4. In the Expires In field, set an expiry for the key or select No expiration. Valid time units are "s", "m", "h", "d", "w" or put 0 for no expiry. 5. Assign a Role [(Owner, Member)](./index.md#roles) that you want to assign to the key. 6. Click the Create button. 7. Copy the values for `AKUITY_API_KEY_ID` and `AKUITY_API_KEY_SECRET` ## Using your API key You can use your API key with the [akuity CLI](../03-automation/index.mdx) or the [Akuity API](../03-automation/30-api.mdx). --- ## Akuity Platform Audit Logs ## Audit Logs The Audit Logs feature allows you to view all the actions taken by users in your organization. This feature is useful for organizations that need to track the actions taken by users for compliance reasons or for organizations that need to troubleshoot issues. The Audit Logs feature is available to users with the `Owner` role. To view the Audit Logs, follow these steps: 1. Select the Organization you want to view the audit logs for, from the pull down menu. 2. Switch to the Audit Logs tab. 3. The Audit Logs page will display a list of all the actions taken by users in your organization. The list includes the following information: - `Timestamp`: The date and time the action was taken. - `Object`: The object the action was taken on. - `Actor`: The user who took the action. - `Action`: The action taken by the user. - `Details`: Additional details about the action. ![Audit Tab](/img/audit_logs_0.png) Instance level audit logs are also available. They show the actions taken on a particular Argo CD or Kargo instance in your organization. To view the instance level audit logs, follow these steps: 1. Select the Organization you want to view the audit logs for, from the pull down menu. 2. Switch to the ArgoCD or Kargo tab. 3. Click on the instance you want to view the audit logs for. 4. Click on the Audit Logs tab. 5. The Audit Logs page will display a list of all the actions taken on the instance. ![Instance Audit Tab](/img/audit_logs_1.png) ## Audit Logs Archive The Audit Logs Archive is a feature that allows you to download a ZIP file of the weekly audit logs for your organization. This feature is useful for organizations that need to store audit logs for compliance reasons or for organizations that need to analyze the audit logs in a different tool. The Audit Logs Archive feature is available to users with the `Owner` role. To download the Audit Logs Archive, follow these steps: 1. Select the Organization you want to download the audit logs for, from the pull down menu. 2. Switch to the Audit Logs tab. 3. Click the Archive button on the upper right side of the page. ![Archive Button](/img/audit_logs_2.png) 4. Click the Download icon to download the logs of the corresponding week. ![Download Logs](/img/audit_logs_3.png) 5. The ZIP file will contain a JSON file for each day of the week. The audit logs are created weekly. The ZIP file will contain a JSON file for each day of the week. The JSON files contain the audit logs for that day. --- ## Akuity Platform Custom Roles Custom roles add support for Role Based Access Control (RBAC) for resources in the Akuity Platform (e.g. an Instance, or an Organization). Users can create and attach custom roles to API Keys to limit their access. :::note Support for custom roles on organization members is coming soon. ::: ## Managing Custom Roles Only users with the Owner role in an organization can manage custom roles. They are read-only for everyone else. 1. Select the Organization you want to create a role for, from the pull down menu. 2. Switch to the Custom Roles tab. 3. Click on the "Create New Role" button to create a new role. ![Manage Custom Roles](/img/custom_roles_01.png) 4. Provide the name, description, and permissions of role. Then create the role. Please note that you can only add granular permissions for ArgoCD Instance, ArgoCD Cluster, Kargo Instance and Kargo Agent. ![Create Custom Role Modal](/img/custom_roles_02.png) 5. You can then use that role when creating an API key. ![API keys](/img/custom_roles_03.png) ## Available permissions Here is a table of current permissions which can be used in a custom role | Resource | Get | Create | Update | Delete | |-------------------|-----|--------|--------|--------| | Organization | ✅ | ❌ | ✅ | ✅ | | Custom Roles | ✅ | ✅ | ✅ | ✅ | | Billing | ✅ | ✅ | ✅ | ✅ | | API Keys | ✅ | ✅ | ✅ | ✅ | | Argo CD Instance | ✅ | ✅ | ✅ | ✅ | | Argo CD Cluster | ✅ | ✅ | ✅ | ✅ | | Kargo Instance | ✅ | ✅ | ✅ | ✅ | | Kargo Agent | ✅ | ✅ | ✅ | ✅ | | SSO Configuration | ✅ | ✅ | ✅ | ✅ | | Member Role | ❌ | ❌ | ✅ | ❌ | | Audit Log | ✅ | ❌ | ❌ | ❌ | | OIDC Map | ✅ | ❌ | ✅ | ❌ | | Notification Config | ✅ | ✅ | ✅ | ✅ | | Teams | ✅ | ✅ | ✅ | ✅ | | Team Members | ✅ | ✅ | ❌ | ✅ | | Workspaces | ✅ | ✅ | ✅ | ✅ | | Workspace Members | ✅ | ✅ | ❌ | ✅ | | Workspace Member Role| ❌ | ❌ | ✅ | ❌ | | Workspace API Keys | ✅ | ✅ | ✅ | ✅ | | Workspace Custom Role| ✅ | ✅ | ✅ | ✅ | | Kubernetes Dashboard | ✅ | ❌ | ❌ | ❌ | | Akuity Intelligence | ✅ | ✅ | ✅ | ✅ | --- ## Notifications Notifications are a way to keep track of important events on the Akuity Platform. You can receive notifications for a variety of events, such as usage alerts of applications, audit logs, and more. Notifications can be sent using 3 different methods: email, webhook, and Akuity Platform UI. For critical communications from the Akuity team, such as security advisories and major platform changes, see [Technical Contacts](./100-technical-contacts.md). ## Notification Center The Notification Center is where you can view all the notifications that have been sent to you through Akuity Platform UI. You can access the Notification Center by clicking on the bell icon (🔔) in the top right corner of the Akuity Platform and then clicking on Notifications Center. The Notification Center will display all the notifications that have been sent to you, and you can view the details of each notification by clicking on it. ![Notification Center](/img/notifications_centre_dashboard.png) ### Settings You can manage your notification settings by going to the Settings tab in the Notification Center page. You can enable or disable notifications for each event type. You can also choose the method of notification for each event type. You can choose to receive notifications via email, or the Akuity Platform UI. ![Notification Settings](/img/notifications_centre_settings.png) #### Notifications Categories The different categories of notifications are: 1. Product Updates - Notifications related to product updates, such as new releases, bug fixes, etc. 1. New Product Version - New product versions related to Akuity Platform. 1. Custom - Custom alerts used by Akuity team. 1. Usage Alerts - Notifications related to usage alerts, such as reaching usage limits, etc. 1. audit - Audit log events. 1. free-trial-expiring - Trial expiration. 1. usage - Usage alert events. 1. Instance Alerts - Notifications related to your instances state. 1. agent-health - Agent health events (connected/disconnected). 1. cname-alert - Domain misconfiguration or expiration. #### Email Notifications Email notifications are sent to the email address associated with your account. An email notification is sent when an event occurs that you have subscribed to. You can manage your email notifications by going to the Settings tab in the Notification Center page. You can enable or disable email notifications for each event type. An example of an email notification for Usage Alerts is shown below: ![Email Notifications](/img/notification_email.png) #### Akuity Platform UI Notifications (Web Notifications) Akuity Platform UI notifications are notifications that are displayed in the Akuity Platform UI. These notifications are displayed in the top right corner of the Akuity Platform, and you can view them by clicking on the bell icon (🔔). Akuity Platform UI notifications are sent when an event occurs that you have subscribed to. You can manage your Akuity Platform UI notifications by going to the Settings tab in the Notification Center page. You can enable or disable Akuity Platform UI notifications for each event type. An example of an Akuity Platform UI notification for Product Updates is shown below: ![Web Notifications](/img/notification_ui.png) ## Organization Notifications Organization notifications allow you to receive alerts for events happening within your organization. These can be configured to be sent via Webhook, Email or Akuity Platform UI (Web). Some notifications like for example usage related are set up by default. ### Webhook Notifications Webhook notifications are sent to a URL that you specify. When a webhook notification is sent, the Akuity Platform will send a POST request to the specified URL with the notification details in the request body. The request body will contain a JSON object with the following fields: - eventTime - The time at which the event occurred. - eventType - The type of event that occurred. - organizationId - The ID of the organization to which the event is related. - eventId - The ID of the event. - <eventTypeData> - Additional data related to the eventType. To set up an organization notification, follow these steps: 1. Select the Organization you want to create a notification for, from the pull down menu. 1. Click on the Settings button. 1. Switch to the Notifications tab. 1. Click the + Add New Notification button. 1. Fill notification details in the dialog. - Type: Select Webhook. - Name: Name of the webhook. - URL: URL of the webhook. - Secret: Secret for validate webhook payload signature. - Events: Event types to subscribe (`*` for all events). Please refer to [notification categories](#notifications-categories) for information about specific events. - Argo CD Instances: If set, webhook will receive events that only related to the chosen Argo CD instances. - Kargo Instances: If set, webhook will receive events that only related to the chosen Kargo instances. - Argo CD Clusters: Only applicable for `agent-health` events. If set, webhook will receive events that only related to the chosen Argo CD clusters. - Kargo Agents: Only applicable for `agent-health` events. If set, webhook will receive events that only related to the chosen Kargo agents. :::note The filter fields above support regular expressions. The value is wrapped in `^...$`. For example, `test.*` matches all names starting with `test`. ::: 1. Click the Add button. ![Webhook Setup](/img/notification_form_webhook.png) The notification will be added to the list. To view the delivery history, click on the View button. ![Webhook Delivery History](/img/notifications_delivery_history.png) Click on the Send testing event button to send a test event. ![Webhook Testing](/img/notifications_delivery_history_test_event.png) The webhook will be sent a test ping event and the response will be displayed. If you see a tick mark, the webhook was successfully sent. You can click on the + icon to view the response. ![Webhook Testing Response](/img/notifications_delivery_history_test_event_delivery.png) An example of a webhook notification for `audit` event is shown below: ![Audit Webhook](/img/notifications_delivery_history_audit_event_delivery.png) ```json { "eventTime": "2024-08-23T13:21:30.647737Z", "eventType": "WEBHOOK_EVENT_TYPE_AUDIT", "organizationId": "yswhibye4b9xy0e", "eventId": "c2txb45sbae7m5m9", "auditEvent": { "timestamp": "2024-08-23 13:21:30.622450296 +0000 UTC", "action": "created", "actor": { "type": "akuity_user_email", "id": "user@example.com" }, "object": { "type": "custom_role", "id": { "name": "test", "kind": "", "group": "" }, "parentId": { "name": "", "parentName": "", "applicationName": "" } }, "details": { "message": "", "patch": "", "actionType": "" } } } ``` For more information on the webhook schema, refer to the [Notification Webhook Schema](/akuity-portal/reference/notifications). ### Email Notifications Email notifications are sent to the email addresses that you specify. To set up an email notification, follow these steps: 1. Select the Organization you want to create a notification for, from the pull down menu. 1. Click on the Settings button. 1. Switch to the Notification tab. 1. Click the + Add New Notifications button. 1. Fill notification details in the dialog. - Type: Select Email. - Name: Name of the notification configuration. - Recipients: List of email addresses to send notifications to. You can also select org owner through `@org-owner`, everyone in the org with `@org-all` and everyone in the workspace by `@workspace-all` options. - Events: Event types to subscribe (`*` for all events). Please refer to [notification categories](#notifications-categories) for information about specific events. - Argo CD Instances: If set, emails will be sent for events that only related to the chosen Argo CD instances. - Kargo Instances: If set, emails will be sent for events that only related to the chosen Kargo instances. - Argo CD Clusters: Only applicable for `agent-health` events. If set, emails will be sent for events that only related to the chosen Argo CD clusters. - Kargo Agents: Only applicable for `agent-health` events. If set, emails will be sent for events that only related to the chosen Kargo agents. :::note The filter fields above support regular expressions. The value is wrapped in `^...$`. For example, `test.*` matches all names starting with `test`. ::: 1. Click the Add button. ![Email Setup](/img/notification_form_email.png) ### Web Notifications Web notifications are displayed in [Akuity Platform Notifications Centre UI](#akuity-platform-ui-notifications-web-notifications). To set up a web notification, follow these steps: 1. Select the Organization you want to create a notification for, from the pull down menu. 1. Click on the Settings button. 1. Switch to the Notifications tab. 1. Click the + Add New Notification button. 1. Fill notification details in the dialog. - Type: Select Email. - Name: Name of the notification configuration. - Recipients: List of users to send notifications to. You can also select org owner through `@org-owner`, everyone in the org with `@org-all` and everyone in the workspace by `@workspace-all` options. - Events: Event types to subscribe (`*` for all events). Please refer to [notification categories](#notifications-categories) for information about specific events. - Argo CD Instances: If set, emails will be sent for events that only related to the chosen Argo CD instances. - Kargo Instances: If set, emails will be sent for events that only related to the chosen Kargo instances. - Argo CD Clusters: Only applicable for `agent-health` events. If set, emails will be sent for events that only related to the chosen Argo CD clusters. - Kargo Agents: Only applicable for `agent-health` events. If set, emails will be sent for events that only related to the chosen Kargo agents. :::note The filter fields above support regular expressions. The value is wrapped in `^...$`. For example, `test.*` matches all names starting with `test`. ::: 1. Click the Add button. ![Email Setup](/img/notification_form_web.png) --- ## Akuity Platform SSO The Akuity Platform supports the following Single Sign-On (SSO) providers: - [Microsoft (Azure AD)](https://azure.microsoft.com/products/active-directory) - [Google Workspace](https://workspace.google.com) - [Okta](https://www.okta.com) - OpenID Connect - SAML :::info Akuity Platform SSO is available on Enterprise plans only. Please [contact our Sales Team](https://akuity.io/talk-to-sales/) to access the feature. Note that this feature only applies to the Akuity Platform, and is separate from SSO for Argo CD. Argo CD SSO is available in all Professional and Enterprise plans. ::: ## Configuring SSO :::note The `owner` role on the Organization is required to configure SSO. ::: To configure SSO for an Organization on the Akuity Platform: 1. Go to Organization > SSO. ![SSO Settings](/img/sso_settings.png) 2. Click Add Configuration. **Microsoft (Azure AD)** 3. [Register an application with the Microsoft identity platform](https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/azure-active-directory/v2) with the following settings: - Set Redirect URI to `https://auth.akuity.io/login/callback` 4. [Add the following Delegated Permissions to the registered application](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-access-web-apis#add-permissions-to-access-web-apis): - `Users > User.Read` - `Directory > Directory.Read.All` 5. [Generate a client secret.](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app#add-credentials) 6. Populate the configuration details inside the form: - Client ID: Application (client) ID - Client Secret: Client Secret - Azure AD Domain: Your Azure AD domain name. You can find this on your Azure AD directory's overview page in the Microsoft Azure portal. - Domain Aliases: Additional domains to match organization members (e.g. `some-org.com`). - Auto Add Member: Allow your organization members to join your organization with the `member` role automatically. :::note For security purposes, your domain and domain aliases will be submitted to Akuity for manual review and approval. ::: ![Azure SSO Settings](/img/sso_azure.png) **Google Workspace** 3. [Register an application to the Google Workspace](https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/google-apps#set-up-your-app-in-google) with the following settings: - Authorized JavaScript origins to `https://auth.akuity.io` - Set Redirect URI to `https://auth.akuity.io/login/callback` 4. Populate the configuration details inside the form: - Client ID: Application (client) ID - Client Secret: Client Secret - Google Workspace Domain: Google Workspace domain name for your organization. - Domain Aliases: Additional domains to match organization members (e.g. `some-org.com`). - Auto Add Member: Allow your organization members to join your organization with the `member` role automatically. :::note For security purposes, your domain and domain aliases will be submitted to Akuity for manual review and approval. ::: ![Google Workspace SSO Settings](/img/sso_google_workspace.png) 5. Test the connection. **Okta** :::caution Okta native integration does not support groups claim, please use generic SAML/OIDC instead if you want to use IDP groups mapping features. ::: 3. Create an Okta OIDC Application. - In your Okta Admin Dashboard, Select Applications > Applications, and Create App Integration. - Select Create New App. - Choose OIDC as the Sign-in method and Web Application as Application Type. - Set Sign-in redirect URIs with `https://auth.akuity.io/login/callback` and select Create. - Copy your `Client ID` and `Client Secret`. - (Optional) You can configure Initiate login URI to skip Akuity login page. - Set Login initiated by under General Settings as Either Okta or App - Set Login flow as OIDC Compliant - Set Initiate login URI as `https://akuity.cloud/api/auth/login/sso/` (ID can be found in Organization tab in Akuity Dashboard) 4. Populate the configuration details on the form. - Client ID: Okta OIDC Application Client ID - Client Secret: Okta OIDC Application Client Secret - Okta Domain: Your [Okta domain](https://developer.okta.com/docs/guides/find-your-domain/main/). - Domain Aliases: Additional domains to match organization members (e.g. `some-org.com`). - Auto Add Member: Allow your organization members to join your organization with the `member` role automatically. :::note For security purposes, your domain and domain aliases will be submitted to Akuity for manual review and approval. ::: ![Okta SSO Settings](/img/sso_okta.png) **OpenID Connect** 3. Create an OIDC Application. - Set Allowed Callback URL to `https://auth.akuity.io/login/callback` 4. Populate the configuration details on the form. - Client ID: OIDC Application Client ID - Email Domain: Your organization's domain name - Domain Aliases: Additional domains to match organization members (e.g. `some-org.com`). - Channel: - `Front Channel` uses `response_mode=form_post` and `response_type=id_token` - `Back Channel` uses `response_type=code` - Discovery URL: OIDC Discovery URL to fill Issuer details - Issued details: - Client Secret: OIDC Application Client Secret (required for the `Back Channel`) - Issuer: URL of the Issuer Identifier. - Authorization Endpoint: URL of the OpenID Provider's OAuth 2.0 Authorization Endpoint. - Token endpoint: URL of the OpenID Provider's OAuth 2.0 Token Endpoint (required for the `Back Channel`). - Jwks URL: URL of the OpenID Provider's JSON Web Key Set document. - Auto Add Member: Allow your organization members to join your organization with the `member` role automatically. :::note For security purposes, your domain and domain aliases will be submitted to Akuity for manual review and approval. ::: ![OIDC SSO Settings](/img/sso_oidc.png) **SAML** 3. Create an OIDC Application. - Set Allowed Callback URL to `https://auth.akuity.io/login/callback?connection={your organization id}` - Set Entity ID to `urn:auth0:akuity:{your organization id}` - Organization ID can be found in the top-right side of the `Organization` page. ![SAML Organization ID](/img/sso_saml_org_id.png) 4. Populate the configuration details on the form. - Domain: Your organization's domain name - Domain Aliases: Additional domains to match organization members (e.g. `some-org.com`). - Configuration (XML): Use Metadata XML to configure SAML SSO. - Configuration (Manual): Manually configure SAML SSO. - Sign-In Endpoint: SAML single login URL. - Disable Sign-out: When disabled, a specific Sign Out URL can be set. - Sign-Out Endpoint: SAML single logout URL. - Sign Request: When enabled, the SAML authentication request will be signed. - Signature Algorithm: Algorithm to use to sign the SAML assertions. - Digest Algorithm: Algorithm to use to the sign request digest - Base64 Encoded Signing Cert: Base64 encoded signing certificate - Protocol Binding: HTTP binding supported by the IdP - IdP Initiated SSO: When enabled, users can log in directly from their Identity Provider without first visiting the Akuity Platform. :::warning Security Risk: IdP-Initiated SSO Auth0, the identity provider powering Akuity Platform authentication, does not recommend enabling IdP-Initiated SSO. In an IdP-Initiated flow, Auth0 receives an unsolicited response from the IdP and the application receives an unsolicited response from Auth0. Neither entity can verify that the user actually started the flow. This opens the possibility of a **Login CSRF attack**, where an attacker can trick a legitimate user into unknowingly logging into the application with the identity of the attacker. Whenever possible, keep this disabled and let authentication be initiated from the Akuity Platform (the default). Only enable this if your IdP requires initiating the login flow and you understand the risks involved. ::: :::note For security purposes, your domain and domain aliases will be submitted to Akuity for manual review and approval. ::: ![SAML SSO Settings](/img/sso_saml.png) **Okta with SAML** 3. In your Okta Admin Dashboard, go to Applications -> Applications -> Create App Integration ![Create App Integration](/img/sso_okta_1.png) 4. Select SAML 2.0 as the Sign-in method, and click Next ![SAML 2.0](/img/sso_okta_2.png) 5. Provide the app name and logo, then click Next. ![App Name](/img/sso_okta_3.png) 6. In Configure SAML section set : a. Single Sign-On URL: `https://auth.akuity.io/login/callback?connection=` b. Audience URI (SP Entity ID): `urn:auth0:akuity:` c. In the Attributes Statements section, add : | Name | Name format | Value | |-------------|-------------|----------------| | email | Unspecified | user.email | | given_name | Unspecified | user.firstName | | family_name | Unspecified | user.lastName | d. In the Group Attribute Statements section, add the following (you can modify the group regex according to your needs) : | Name | Name format | Filter | |-------------|-------------|----------------------| | groups | Unspecified | Matches regex : `.*` | ![Configure SAML](/img/sso_okta_4.png) e. Click Next and Finish ![Configure SAML Next](/img/sso_okta_5.png) 7. Go to the Application details page, select Sign On tab and then find and click the View SAML setup instructions button on the right side ![App Details Page](/img/sso_okta_6.png) 8. This will open a `How to Configure SAML 2.0 for Application` page, where you can find the XML IDP metadata. Copy the XML. ![XML Config](/img/sso_okta_7.png) 7. Now, go to Akuity, and from the Type dropdown select SAML. 9. Choose XML as the Configuration type and paste the Metadata you copied in the Metadata XML input. ![Add Metadata](/img/sso_okta_9.png) 10. Add your SSO email domain in the Domain input field 11. Click on the Enforce SSO toggle if you want to enforce SSO login for your organization members. If this is disabled, users will have the option to log in with SSO or with social login like Google. :::warning Important Enforcing SSO will require all organization users to use SSO for login. If your SSO configuration is broken, you may be locked out from your account and require contact with support. Make sure to thoroughly test your SSO configuration before enforcing it for all users. ::: 12. Optionally, enable the IdP Initiated SSO toggle if you want users to be able to log in directly from Okta without first visiting the Akuity Platform. :::warning Security Risk: IdP-Initiated SSO Auth0, the identity provider powering Akuity Platform authentication, does not recommend enabling IdP-Initiated SSO. In an IdP-Initiated flow, Auth0 receives an unsolicited response from the IdP and the application receives an unsolicited response from Auth0. Neither entity can verify that the user actually started the flow. This opens the possibility of a **Login CSRF attack**, where an attacker can trick a legitimate user into unknowingly logging into the application with the identity of the attacker. Whenever possible, keep this disabled and let authentication be initiated from the Akuity Platform (the default). Only enable this if your IdP requires initiating the login flow and you understand the risks involved. ::: 13. Create the configuration by clicking the Add button. 13. Now, if you try to log in with an email associated with the domain you just configured, you will be redirected to Okta. ## IDP Groups Mapping :::caution IDP Groups does not work for Okta native integration as Okta does not support groups claim. Please use generic SAML/OIDC option instead to connect with Okta if you want to use this feature. ::: To configure IDP Groups for an Organization in the Akuity Platform: 1. Go to Organization > SSO. ![OIDC SSO Settings](/img/sso_oidc_0.png) 2. Click Add New Rule. ![Add New Rule](/img/sso_oidc_1.png) 3. In the Add OIDC Group Mapping select the role and specify the corresponding OIDC Group for your provider. ![Add OIDC Group Mapping](/img/sso_oidc_2.png) 4. Click the Add button. :::note In the SSO settings, if the Auto Add Member is checked the new user willjoin your organization with the `member` role automatically. ![Auto Add Member](/img/sso_oidc_3.png) ::: ## OIDC Team Mapping :::caution OIDC Team Mapping does not work for Okta native integration as Okta does not support groups claim. Please use generic SAML/OIDC option instead to connect with Okta if you want to use this feature. ::: This feature allows you to map users with a specific OIDC group to a team in your organization. Your organization must have at least one Team. To configure this feature for an Organization in the Akuity Platform: 1. Go to Organization > SSO. ![OIDC SSO Settings](/img/sso_oidc_0.png) 2. Scroll down to the "OIDC Team Mapping" section and click Add New Mapping. ![Add New Rule](/img/sso_oidc_team_1.png) 3. In the modal that appears, specify an OIDC group and select an existing team from the dropdown. ![Add IDP Team Mapping](/img/sso_oidc_team_2.png) 4. Click the Add button. Now, when a user logs in with the specified IDP group, they will be added to the selected team in your organization. --- ## Akuity Platform Teams Teams are a way to group users within an organization. :::info Akuity Platform Teams is available on Professional and Enterprise plans only. Please [contact our Sales Team](https://akuity.io/talk-to-sales/) to access the feature. ::: :::note The `owner` role on the Organization is required to manage teams. The `member` role can only view teams. ::: ## Managing Teams To create a team in an organization: 1. Go to Organization > Teams. Click Add Team button on the lower left side of the page. ![Teams Tab](/img/teams_01.png) 2. Enter a Name and a Description for the team, then click Add. ![Add Team](/img/teams_02.png) To update the team description: 1. Click the second button on the right side of the team. ![Update Team](/img/teams_03.png) 2. Enter the new description and click Save. ![Update Description](/img/teams_04.png) To delete a team: 1. Click the third button on the right side of the team. ![Delete Team](/img/teams_05.png) 2. Click Confirm to confirm the deletion. ![Delete Confirmation](/img/teams_06.png) ## Managing Members in a Team: To add members to a team: 1. Click the first button on the right side of the team just created. ![Add Members](/img/teams_07.png) 2. Switch Add tab. Use the search bar to find the Organization members you want to add to the team, and click Add on the right side of the member to add them to the team. ![Add Member](/img/teams_08.png) To remove a member from the team: 1. Switch to the Members tab. 2. Click the Delete button on the right side of the member to remove them from the team. ![Remove Member](/img/teams_09.png) --- ## Akuity Platform Workspaces Workspaces are a way to group resources within an organization. Argo CD instances, Kargo instances, Organization users and Teams can be grouped into Workspaces. :::info Akuity Platform Workspaces is available on all plans. Different plans have different limits on the number of Workspaces that can be created: - **Starter**: 1 Workspace - **Professional**: 3 Workspaces - **Enterprise**: Unlimited Workspaces Please [contact our Sales Team](https://akuity.io/talk-to-sales/) to change your plan if you need more Workspaces. ::: :::note The `owner` role on the Organization is required to manage Workspaces, including creating, updating, and deleting them. ::: ## Roles ### Admin Admins have full access to all resources within the Workspace. They can add or remove Argo CD instances, Kargo instances, Organization users and Teams from the Workspace. They can not delete the Workspace itself. The user who creates the Workspace automatically assumes an Admin role. ### Member Members get read access to all resources within the Workspace, but cannot edit any settings. They also have no access to Workspace settings. ## Managing Workspaces When creating an Organization, a default Workspace is created automatically. Click the Organization drop-down on the left navigation menu and click Workspaces to view the all Workspaces in an Organization. ![Default Workspace](/img/workspaces_01.png) To create a new Workspace: 1. Click Create button on the upper right side of the page. ![Create Workspace](/img/workspaces_02.png) 2. Enter a Name and a Description for the Workspace, then click Create. ![Add Workspace](/img/workspaces_03.png) To update the Workspace name or description: 1. Click the Workspace on the Workspaces page. ![Update Workspace](/img/workspaces_04.png) 2. Click the Settings tab and click the General menu. ![Workspace Settings](/img/workspaces_05.png) 3. Enter the new name or description and click Save. ![Update Description](/img/workspaces_06.png) To delete a Workspace: 1. Enter the Workspace name under the Danger Zone section. 2. Click the I know what I am doing, delete workspace button to confirm the deletion. ![Delete Workspace](/img/workspaces_07.png) ## Managing Users and Teams in Workspaces Workspace admin can add or remove users and teams from the Workspace. To add a user or a team to a Workspace: 1. Click the Settings tab and click the Teams and People menu. ![Workspace Settings](/img/workspaces_08.png) 2. User the search bar to find the Organization user or Teams you want to add to the Workspace. ![Search Member](/img/workspaces_09.png) 3. Select the workspace role in the drop-down and click Add to add them to the Workspace. ![Add Member](/img/workspaces_10.png) To change the role of a user or a Team in a Workspace: 1. Click the role drop-down and select the new role for a user or a Team. ![Change Role](/img/workspaces_11.png) To remove a user or a Team from a Workspace: 1. Click the Remove button on the right side of the user or Team, and click the Confirm button on the pop-up to confirm the removal. ![Remove Member](/img/workspaces_12.png) ## Creating an API Key 1. Switch to the API Keys tabs ![API Settings](/img/workspaces_13.png) 2. Click + New Key button on the lower right side of the page ![Create API Key](/img/workspaces_14.png) 3. Enter a Description for the key. ![API Description](/img/workspaces_15.png) 4. In the Expires In field, set an expiry for the key or select No expiration. Valid time units are "s", "m", "h", "d", "w" or put 0 for no expiry. 5. Assign a Role [(Admin, Member)](#roles) that you want to assign to the key. 6. Click the Create button. 7. Copy the values for `AKUITY_API_KEY_ID` and `AKUITY_API_KEY_SECRET` ## Custom Roles Custom roles can be created to provide more granular access to resources within a Workspace. Only the `owner` of the Organization or the `Admin` of the Workspace can create custom roles. It is read-only for Workspace `Member` role. To create a custom role for a particular workspace: 1. Click the Settings tab and click the Custom Roles menu. ![Workspace Settings](/img/workspaces_16.png) 2. Click the + Create New Role button. ![Create Role](/img/workspaces_17.png) 3. Provide the name, description, and permissions of role. Then create the role. ![Role Details](/img/workspaces_18.png) 4. You can then use that role when creating an API key for the Workspace. ![API Custom Role](/img/workspaces_19.png) ### Available Permissions Here is a table of current permissions which can be used in a custom role | Resource | Get | Create | Update | Delete | |-------------------|-----|--------|--------|--------| | Members | ✅ | ✅ | ❌ | ✅ | | ArgoCD Instances | ✅ | ✅ | ✅ | ✅ | | ArgoCD Clusters | ✅ | ✅ | ✅ | ✅ | | Kargo Instances | ✅ | ✅ | ✅ | ✅ | | Kargo Agents | ✅ | ✅ | ✅ | ✅ | | API Keys | ✅ | ✅ | ✅ | ✅ | | Custom Roles | ✅ | ✅ | ✅ | ✅ | | Member Role | ❌ | ❌ | ✅ | ❌ | --- ## SSO Domain Verification Domain verification lets your organization confirm ownership of email domains for use with SSO configuration. Once a domain is verified, it can be added as a domain alias in your organization's SSO settings. :::info Domain verification is managed by your organization's owners. Contact Akuity Support if you encounter issues during the verification process. ::: ## Add a Domain Alias 1. Navigate to **Organizations > Settings > Domain Verification**. 2. In the **New Domain Aliases** field, type your domain (e.g. if your org email is `user@example.com`, enter `example.com`). ![Add Domain Alias](/img/domain-verification_1.png) 3. Press **Enter** to add multiple domains and click **+ New**. :::note Akuity team will review your request and approve the domain on their end. ::: ## Verification Status The domain table shows the current status for each alias: | Status | Description | |----------|--------------------------------------------------| | Verified | Domain ownership confirmed; available for SSO | | Pending | Domain added but verification not yet complete | Once a domain is **Verified**, it can be used as a tenant domain or domain alias in your organization's [SSO](https://docs.akuity.io/akuity-portal/organizations/sso) configuration. --- ## Multi Factor Authentication Multi Factor Authentication (MFA) is a security feature that requires users to provide two or more verification factors to access the Akuity Platform. This adds an extra layer of security to your account and helps protect your data. :::note IMPORTANT Multi Factor Authentication is available at the organization level. Once MFA is enabled, **every user** in the organization *must* set up MFA to access the Akuity Platform. Otherwise, users will not be able to log in. ::: :::info MFA is available on Professional and Enterprise plans only. Please [contact our Sales Team](https://akuity.io/talk-to-sales/) to access the feature. This feature is only available on SaaS and not available on Self-Hosted. The `owner` role on the Organization is required to manage MFA settings. ::: ## Enabling MFA To enable MFA for your organization: 1. Click the Organization drop-down on the left navigation menu and click Settings. ![Organization Settings](/img/mfa_1.png) 2. Click the MFA tab. ![MFA Settings](/img/mfa_2.png) 3. Click the Enabled toggle and confirm the action. ![Enable MFA](/img/mfa_3.png) 4. MFA has been enabled. **Remember: every user in the organization must set up MFA** to access the Akuity Platform. The next time a user logs in, they will be prompted to set up MFA. ## Managing MFA You can view the MFA status of all users in the organization on the MFA page. The MFA status can be one of the following: - **Enrolled**: The user has set up MFA. - **Not Enrolled**: The user has not set up MFA. ![Manage MFA](/img/mfa_4.png) In case a user is locked out of their account and they can no longer access the MFA code, the organization `owner` can reset the MFA for the user. To reset MFA for a user: 1. Click on the three dots next to the user and click Reset MFA. 2. This will send a request to the support team to reset the MFA for the user. The support team will reset the MFA for the user. Once MFA is reset for a user, the user will be prompted to set up MFA the next time they log in. --- ## Quotas Quotas in the Akuity Platform help organizations manage and control resource usage effectively. By setting quotas, organizations can ensure that instances do not exceed allocated resources, maintaining optimal performance and cost management. Quotas can be set for different Argo CD and Kargo instances within the organization. Each Argo CD instance can have a quota for the maximum number of applications allowed, while each Kargo instance can have quotas for different stages. ## Managing Quotas To manage quotas for your organization: 1. Click the Organization drop-down on the left navigation menu and click Settings. ![Organization Settings](/img/quotas_1.jpg) 2. Click the Quotas tab. ![Quotas Settings](/img/quotas_2.jpg) 3. Here, you can view and manage the quotas for different Argo CD and Kargo instances. 4. To add a new quota for the Argo CD instance, go to the Deploy tab and click on the Add New Quotas button. ![Add Quota](/img/quotas_3.jpg) 5. In the Name dropdown, you can select the instance for which you want to set the quota. Next to that is the Applications Limit field where you can set the maximum number of applications allowed for that instance. After setting the desired values, click on the Add button to save the changes. ![Set Quota](/img/quotas_4.jpg) 6. The new quota will be added to the list of quotas for the organization. Here, you can see the current application count and the applications limit for the instance. ![Quota Added](/img/quotas_5.jpg) 7. A similar process can be followed to add quotas for Kargo instances by navigating to the Promote tab. You can add limits for the stages for each Kargo instance. ![Kargo Quotas](/img/quotas_6.jpg) --- ## Organizations Organizations provide control over your Akuity Platform resources by allowing team members different levels of access within the organization. ## Changing contexts If you belong to multiple organizations, the dashboard's context switcher component is useful for selecting which of those organization you intend to actively work with. The context switcher is a drop-down list located at the top of the left navigation menu, directly under the Akuity logo. ### Organizations across regions The Akuity Platform operates across multiple regions. If you have organizations in more than one region, they all appear together in a single view inside the context switcher. Selecting an organization from a different region will redirect you to that region's portal. ## Roles ### Owner Owners have full access to all Argo CD instances owned by the organization. They have permission to edit all organization settings and download archives of the organization's Audit Log records. The user who creates the organization automatically assumes an Owner role. ### Member Members get access to Argo CD instances owned by the organization, but cannot edit instance settings. They also have no access to organization settings. ### Custom Members with the Owner role in an organization can manage custom roles, which can then be assigned to API Keys. Read more about [Custom Roles](/akuity-portal/organizations/custom-roles) --- ## Akuity Platform Declarative Management ## Platform-specific settings Declarative management of platform-specific settings is implemented using [`akuity` CLI](/akuity-portal/automation). ### Managing Argo CD Instances Use the following steps to manage existing Argo CD instances with the Akuity Platform: 1. **Export Configuration**: Use the `akuity argocd export --organization-name ` command to export the existing instance configuration. > Note: `yq` provides a convenient way to split the output into multiple files. ```shell akuity argocd export demo --organization-name demo | yq -s '.metadata.name' - ``` 1. **Compare Configuration**: Use the `akuity argocd diff --organization-name ` command to compare local configuration with the current state of the Akuity Platform. ```shell akuity argocd diff demo --organization-name demo -f argocd/demo/ ``` 1. **Apply Changes**: Use the `akuity argocd apply -f ` command to apply changes to the Akuity Platform. ```shell akuity argocd apply -f argocd/demo/ ``` #### Configuration specifications The declarative configuration that defines Argo CD instance state has the same format as open-source Argo CD and described [here](https://argo-cd.readthedocs.io/en/stable/operator-manual/declarative-setup/). The Akuity Platform specific settings, such as instance name, IP allows lists and other additional features are defined using `argocd.akuity.io/v1alpha1/ArgoCD` resource. Example of the declarative configuration: ```yaml apiVersion: argocd.akuity.io/v1alpha1 kind: ArgoCD metadata: name: test-inst spec: version: v2.6.0 description: test-inst instanceSpec: ipAllowList: - ip: "1.2.3.4" description: dummy entry declarativeManagementEnabled: true ``` The reference specifications are available [here](../../../../akuity-portal/reference/declarative-specs). ### Managing Kargo Instances Use the following steps to manage existing Kargo instances with the Akuity Platform: 1. **Export Configuration**: Use the `akuity kargo export --organization-name ` command to export the existing instance configuration. ```shell akuity kargo export demo --organization-name demo | yq -s '.metadata.name' - ``` 1. **Compare Configuration**: Use the `akuity kargo diff --organization-name ` command to compare local configuration with the current state of the Akuity Platform. ```shell akuity kargo diff demo --organization-name demo -f kargo/demo/ ``` 1. **Apply Changes**: Use the `akuity kargo apply -f ` command to apply changes to the Akuity Platform. ```shell akuity kargo apply -f kargo/demo/ ``` #### Configuration specifications The reference specifications are available [here](../../../../akuity-portal/reference/declarative-specs). ### Automated workflow The GitOps workflow is implemented using GitHub Actions and is provides the following experience: 1. Engineers make changes to the declarative configuration of the Akuity Platform in the `argocd` directory and create Pull Request with the proposed changes. 1. GitHub action workflow compares the proposed changes with the current state of the Akuity Platform and posts detected changes as a comment to the Pull Request. 1. Reviewers review the proposed changes and detected changes report and approve the Pull Request. 1. GitHub action workflow applies the proposed changes to the Akuity Platform. See the example live demo at https://github.com/akuity/akp-declarative/. --- ## Agent installation with Helm The Akuity Platform provides an official Helm chart for installing and registering the Akuity agent on a cluster. The chart handles both registering the agent with the Akuity Platform and deploying the agent components in a single step. It supports both **Argo CD** cluster agents and **Kargo** agents, selected with the `agentType` value. The chart is published to the OCI registry at `oci://quay.io/akuity/akuity-platform-charts/akuity-agent`. ## Overview When installed, the chart runs a registration job that: 1. Creates (or upserts) the agent entry in the Akuity Platform using the Akuity CLI. 2. Fetches the generated agent manifests from the platform. 3. Applies the agent manifests to the cluster. The agent is designed to be provisioned as part of a cluster bootstrapping process. Rather than registering clusters manually after they are created, we recommend embedding this Helm chart into the platform infrastructure that is already in place. For example Terraform - so that every new cluster is registered automatically on creation. ## Choosing the agent type The `agentType` value selects which agent to install: - `argocd` (default) — registers the cluster with an Argo CD instance and installs the Argo CD cluster agent. - `kargo` — registers a Kargo agent with a Kargo instance and installs the Kargo agent. In both cases `clusterName` is the name the agent is registered under (the cluster name for Argo CD, the agent name for Kargo) and `instanceName` is the Argo CD or Kargo instance to attach to. ## Prerequisites - An Akuity Platform organization and an existing Argo CD or Kargo instance to register the agent with. - An Akuity API key. Generate one from the **API Keys** tab on the organization profile page in the Akuity Portal UI, or see [the CLI reference](../05-reference/cli/index.mdx) for the `akuity apikey create` command. - Helm v3 and `kubectl` access to the target cluster. ## Installing an Argo CD agent ```sh helm install akuity-agent oci://quay.io/akuity/akuity-platform-charts/akuity-agent \ --namespace akuity-agent \ --create-namespace \ --set clusterName= \ --set instanceName= \ --set organizationName= \ --set akuityApiKeyId= \ --set akuityApiKeySecret= ``` `agentType` defaults to `argocd`, so it does not need to be set explicitly. ## Installing a Kargo agent ```sh helm install akuity-kargo-agent oci://quay.io/akuity/akuity-platform-charts/akuity-agent \ --namespace akuity \ --create-namespace \ --set agentType=kargo \ --set clusterName= \ --set instanceName= \ --set organizationName= \ --set akuityApiKeyId= \ --set akuityApiKeySecret= ``` By default the chart installs a **self-hosted** Kargo agent (`kargo.selfHosted=true`): the agent runs in your cluster and the chart applies its manifests. The Kargo agent installs a mutating admission webhook in its namespace; the registration job waits for that webhook to become ready before completing, so the install may take a little longer than the Argo CD agent. Set `kargo.selfHosted=false` for an **Akuity-managed** agent. In that case the agent is run by Akuity, no manifests are produced for the cluster, and the chart only registers the agent (it does not apply anything to your cluster). :::warning Each Kargo agent should be installed into a single namespace. The Kargo agent's webhook selects namespaces by the agent's instance and name labels, so reusing the same `clusterName` (agent name) and `instanceName` across multiple namespaces can cause their webhooks to interfere with each other. Use a distinct `clusterName` per agent. `helm uninstall` removes the registration job but does **not** remove the in-cluster Kargo agent, including its cluster-scoped `MutatingWebhookConfiguration`. To remove an agent, delete it from the Akuity Portal UI so the platform tears down its in-cluster resources cleanly. Leaving an agent's resources behind (for example by deleting its namespace manually) can orphan the webhook configuration and block future installs. ::: ## Configuration reference ### Common values | Value | Description | Required | |---|---|---| | `agentType` | Agent to install: `argocd` (default) or `kargo` | No | | `clusterName` | Name to register the agent under (cluster name for Argo CD, agent name for Kargo) | Yes | | `instanceName` | Name of the Argo CD or Kargo instance to register with | Yes | | `organizationName` | Name of your Akuity organization | Yes | | `akuityApiKeyId` | Akuity API key ID | Yes | | `akuityApiKeySecret` | Akuity API key secret | Yes | | `akuityServerUrl` | Akuity Platform API URL (defaults to `https://akuity.cloud`) | No | | `version` | Pin a specific agent version | No | | `agentSize` | Agent resource size | No | | `labels` | Labels to apply to the agent, e.g. `["env=prod", "team=platform"]` | No | | `annotations` | Annotations to apply to the agent | No | | `disableAutoUpdate` | Disable automatic agent updates | No | | `extraArgs` | Extra arguments to pass to the agent create command | No | | `rbac.extraRules` | Extra policy rules appended to the registration job's ClusterRole, for granting permissions to additional resources the agent manifests may require | No | ### Argo CD options (`agentType: argocd`) | Value | Description | Required | |---|---|---| | `argocd.project` | Project to associate the cluster with | No | | `argocd.namespaceScoped` | Install the agent in namespace-scoped mode | No | | `argocd.stateReplication` | Enable state replication | No | | `argocd.redisTunneling` | Enable Redis tunneling | No | | `argocd.disableAutoUpgrade` | Disable automatic agent upgrades | No | | `argocd.argoprojCustomImageRegistry` | Custom image registry for Argo CD (argoproj) images | No | :::warning Deprecated The Argo CD options moved under the `argocd.*` key. The previous top-level keys (`project`, `namespaceScoped`, `stateReplication`, `redisTunneling`, `disableAutoUpgrade`, `argoprojCustomImageRegistry`) are **deprecated** but still honored for backwards compatibility, and will be removed in a future release. If a value is set both at the top level and under `argocd.*`, the `argocd.*` value takes precedence (for booleans, either being `true` enables the flag). Migrate existing values files to the `argocd.*` keys. ::: ### Kargo options (`agentType: kargo`) | Value | Description | Required | |---|---|---| | `kargo.selfHosted` | Run the agent in this cluster (`true`, default) or as an Akuity-managed agent (`false`) | No | | `kargo.agentNamespace` | Namespace to install the Kargo agent into (defaults to the release namespace) | No | | `kargo.akuityArgocdName` | Name of an Akuity-managed Argo CD instance to associate with this agent | No | | `kargo.selfManagedArgocdUrl` | URL of a self-managed Argo CD instance to associate with this agent | No | | `kargo.argocdNamespace` | Target Argo CD namespace for the agent | No | | `kargo.kargoCustomImageRegistry` | Custom image registry for Kargo images | No | | `kargo.akuityCustomImageRegistry` | Custom image registry for Akuity images | No | | `kargo.kustomizationPath` | Path to a `kustomization.yaml` with extra Kargo agent kustomizations | No | | `kargo.defaultShard` | Set this agent as the instance's default shard | No | ## Embedding in Terraform For clusters managed by Terraform, use the [`helm_release`](https://registry.terraform.io/providers/hashicorp/helm/latest/docs/resources/release) resource to register each cluster as part of provisioning. This ensures the agent is always installed when a new cluster is created, without any manual steps. ```hcl variable "akuity_api_key_id" { type = string sensitive = true } variable "akuity_api_key_secret" { type = string sensitive = true } resource "helm_release" "akuity_agent" { name = "akuity-agent" repository = "oci://quay.io/akuity/akuity-platform-charts" chart = "akuity-agent" namespace = "akuity-agent" create_namespace = true set { name = "clusterName" value = var.cluster_name } set { name = "instanceName" value = var.argocd_instance_name } set { name = "organizationName" value = var.akuity_organization_name } set { name = "akuityApiKeyId" value = var.akuity_api_key_id type = "string" } set_sensitive { name = "akuityApiKeySecret" value = var.akuity_api_key_secret } } ``` :::note Store `akuityApiKeyId` and `akuityApiKeySecret` in a secrets manager (such as AWS Secrets Manager or HashiCorp Vault) and pass them into Terraform as sensitive variables rather than hardcoding them in the configuration. ::: --- ## The Akuity API The Akuity API allows you to manage the Akuity Platform resources using the REST API. ## Getting an API Key In order to use the API you will first need to [create an API key](../02-organizations/20-api-keys.mdx). Copy the following values from your API key: - `AKUITY_API_KEY_ID` - `AKUITY_API_KEY_SECRET`. ## Accessing the API :::note The API Server address is `https://akuity.cloud/api/v1/` You can browse the [current API Reference](../05-reference/api.mdx). ::: You can connect from your local workstation, with any tool that speaks HTTP (such as [postman](https://www.postman.com), [httpie](https://httpie.io), [curl](https://curl.se), [wget](https://www.gnu.org/software/wget/) etc.). ## Authentication The API allows you to authenticate via HTTP basic auth using the `Authorization` Header. ### Basic Auth [Basic auth](https://en.wikipedia.org/wiki/Basic_access_authentication) has been around for a long time, and is pretty simple. You will pass in a http header that looks like this. ```sh Authorization: Basic ``` where credentials is the [Base64](https://en.wikipedia.org/wiki/Base64) encoding of `AKUITY_API_KEY_ID` and `AKUITY_API_KEY_SECRET` joined by a single colon : ```sh export AKUITY_API_KEY_ID=mySecretKeyId export AKUITY_API_KEY_SECRET=blahblahSecretValueBlahblah export API_CRED=`echo -n $AKUITY_API_KEY_ID:$AKUITY_API_KEY_SECRET | base64` echo -n $API_CRED > bXlTZWNyZXRLZXlJZDpibGFoYmxhaFNlY3JldFZhbHVlQmxhaGJsYWg= ``` :::note In zsh, a `%` symbol is placed at the end of a line where zsh inserted a newline for us. It is important to include echo’s -n option when piping content to an encoder to avoid a newline character being included in the encoded output. If the credentials are not working, check to make sure your base64 encoded value is correct ```sh echo -n "$AKUITY_API_KEY_ID:$AKUITY_API_KEY_SECRET" | base64 | base64 -d ``` ::: ## API Examples **curl** ### Curl This command will returns the organizations for this API KEY using the basic auth header. ```sh curl -H "Authorization: Basic `echo -n $AKUITY_API_KEY_ID:$AKUITY_API_KEY_SECRET | base64`" https://akuity.cloud/api/v1/organizations ``` This is the same command, but we are using the basic auth `-u` flag in Curl. Which is a little easier since we don't need to Base64 encode the header ourselves. ```sh curl -u $AKUITY_API_KEY_ID:$AKUITY_API_KEY_SECRET https://akuity.cloud/api/v1/organizations ``` **httpie** ### httpie This command will returns the organizations for this API KEY using the basic auth header. ```sh http -A basic -a $AKUITY_API_KEY_ID:$AKUITY_API_KEY_SECRET https://akuity.cloud/api/v1/organizations ``` **wget** ### wget This command will returns the organizations for this API KEY using the basic auth header. Note: For some reason the `--user`, and `--password` flags didn't work, that is why we are doing it the hard way. ```sh wget -q -O- --header="Authorization: Basic `echo -n $AKUITY_API_KEY_ID:$AKUITY_API_KEY_SECRET | base64`" https://akuity.cloud/api/v1/organizations ``` --- ## The Akuity CLI The Akuity CLI allows you to manage the Akuity Platform resources using the operating system's command line. See [the CLI reference](../05-reference/cli/index.mdx) section for all available commands. ## Installation **Mac** ### Homebrew ```sh brew install akuity ``` ### Manual 1. Download the latest release with the script: ```sh arch=$(uname -m) [ "$arch" = "x86_64" ] && arch=amd64 curl -L -o akuity "https://dl.akuity.io/akuity-cli/$(curl -sL https://dl.akuity.io/akuity-cli/stable.txt)/darwin/${arch}/akuity" ``` The following architectures are available to download: `amd64`, `arm64` :::note To download a specific version, replace the `$(curl -sL https://dl.akuity.io/akuity-cli/stable.txt)` portion of the command with the specific version. For example, to download version v0.9.3 on Mac, use: ```sh arch=$(uname -m) [ "$arch" = "x86_64" ] && arch=amd64 curl -L -o akuity "https://dl.akuity.io/akuity-cli/v0.9.3/darwin/${arch}/akuity" ``` ::: Alternatively, you can download the CLI binary from the Akuity Portal UI using the `CLI` button in the left navigation bar. 2. Make the `akuity` binary executable: ```sh chmod +x ./akuity ``` 3. Move the `akuity` binary to a file location on your system `PATH`. ```sh sudo mv ./akuity /usr/local/bin/akuity sudo chown root: /usr/local/bin/akuity ``` :::note Make sure `/usr/local/bin` is in your `PATH` environment variable. ::: 4. Check whether the version you've installed is the one you wanted: ```sh akuity version ``` :::note If your system shows > "akuity" can't be opened because Apple cannot check it for malicious software. you can allow running it by the following command: ```sh sudo xattr -d com.apple.quarantine /usr/local/bin/akuity ``` ::: **Linux or WSL** 1. Download the latest release with the command: ```sh arch=$(dpkg --print-architecture) curl -sSL -o akuity "https://dl.akuity.io/akuity-cli/$(curl -sL https://dl.akuity.io/akuity-cli/stable.txt)/linux/${arch}/akuity" chmod +x akuity sudo mv akuity /usr/local/bin/akuity ``` The following architectures are available to download: `amd64`, `arm64`, `ppc64le`, `s390x` :::note To download a specific version, replace the `$(curl -sL https://dl.akuity.io/akuity-cli/stable.txt)` portion of the command with the specific version. For example, to download version v0.9.3 on Linux, type: ```sh arch=$(dpkg --print-architecture) curl -sSL -o akuity "https://dl.akuity.io/akuity-cli/v0.9.3/linux/${arch}/akuity" chmod +x akuity sudo mv akuity /usr/local/bin/akuity ``` ::: Alternatively, you can download the CLI binary from the Akuity Portal UI using the `CLI` button in the left navigation bar. 2. Make the `akuity` binary executable: ```sh chmod +x /usr/local/bin/akuity ``` 3. Check whether the version you've installed is the one you wanted: ```sh akuity version ``` **Windows** 1. Download the latest release with the command: ```sh Invoke-WebRequest -URI https://dl.akuity.io/akuity-cli/$(Invoke-WebRequest https://dl.akuity.io/akuity-cli/stable.txt)/windows/amd64/akuity.exe -OutFile akuity.exe ``` The following architectures are available to download: `amd64` :::note To download a specific version, replace the `$(Invoke-WebRequest https://dl.akuity.io/akuity-cli/stable.txt)` portion of the command with the specific version. For example, to download version v0.9.3 on Windows, type: ```sh Invoke-WebRequest -URI "https://dl.akuity.io/akuity-cli/v0.9.3/windows/amd64/akuity.exe" -OutFile akuity.exe ``` ::: Alternatively, you can download the CLI binary from the Akuity Portal UI using the `CLI` button in the left navigation bar. 1. Append or prepend the `akuity` binary folder to your `PATH` environment variable. 1. Check whether the version you've installed is the one you wanted: ```sh akuity version ``` ## Login to Akuity Platform: ```sh akuity login ``` Alternatively, you can generate an API token from the Akuity Portal UI using the API Keys tab on the organization profile page and expose the key using `AKUITY_API_KEY_ID`, `AKUITY_API_KEY_SECRET`, and optionally `AKUITY_SERVER_URL` environment variables: ```sh export AKUITY_API_KEY_ID= export AKUITY_API_KEY_SECRET= akuity argocd instance list --organization-name ``` --- ## API --- ## Akuity ## akuity ``` akuity [flags] ``` ### Options ``` -h, --help help for akuity --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd](akuity_argocd.md) - Interact with ArgoCD resources * [akuity config](akuity_config.md) - Configure Akuity CLI * [akuity kargo](akuity_kargo.md) - Interact with Kargo resources * [akuity login](akuity_login.md) - Authenticate with an Akuity server * [akuity logout](akuity_logout.md) - Remove authentication for an Akuity server * [akuity organization](akuity_organization.md) - Interact with Akuity organizations * [akuity version](akuity_version.md) - Display the version of the Akuity CLI * [akuity whoami](akuity_whoami.md) - Display information about the currently authenticated user --- ## Akuity_argocd ## akuity argocd Interact with ArgoCD resources ``` akuity argocd [flags] ``` ### Options ``` -h, --help help for argocd ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity](akuity.md) - * [akuity argocd addon](akuity_argocd_addon.md) - Interact with ArgoCD Addons * [akuity argocd addon-repo](akuity_argocd_addon-repo.md) - Interact with ArgoCD Addon repos * [akuity argocd apply](akuity_argocd_apply.md) - Apply an Argo CD specification * [akuity argocd cluster](akuity_argocd_cluster.md) - Interact with ArgoCD clusters * [akuity argocd diff](akuity_argocd_diff.md) - Diff an Argo CD specification against local files * [akuity argocd export](akuity_argocd_export.md) - Export an Argo CD specification * [akuity argocd instance](akuity_argocd_instance.md) - Interact with ArgoCD instances --- ## Akuity_argocd_addon Repo ## akuity argocd addon-repo Interact with ArgoCD Addon repos ``` akuity argocd addon-repo [flags] ``` ### Options ``` -h, --help help for addon-repo ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd](akuity_argocd.md) - Interact with ArgoCD resources * [akuity argocd addon-repo create](akuity_argocd_addon-repo_create.md) - Create a addon repo * [akuity argocd addon-repo delete](akuity_argocd_addon-repo_delete.md) - Delete a addon repo * [akuity argocd addon-repo list](akuity_argocd_addon-repo_list.md) - List instance addon repos --- ## Akuity_argocd_addon Repo_create ## akuity argocd addon-repo create Create a addon repo ``` akuity argocd addon-repo create [flags] ``` ### Examples ``` akuity argocd addon-repo create \ --organization-name= \ --instance-name= \ --revision= \ ``` ### Options ``` -h, --help help for create --instance-id string ArgoCD instance ID --instance-name string ArgoCD instance name --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") -r, --revision string Target revision (default "HEAD") ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd addon-repo](akuity_argocd_addon-repo.md) - Interact with ArgoCD Addon repos --- ## Akuity_argocd_addon Repo_delete ## akuity argocd addon-repo delete Delete a addon repo ``` akuity argocd addon-repo delete [flags] ``` ### Examples ``` akuity argocd addon-repo delete \ --organization-name= \ --instance-name= \ ``` ### Options ``` -h, --help help for delete --instance-id string ArgoCD instance ID --instance-name string ArgoCD instance name --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd addon-repo](akuity_argocd_addon-repo.md) - Interact with ArgoCD Addon repos --- ## Akuity_argocd_addon Repo_list ## akuity argocd addon-repo list List instance addon repos ``` akuity argocd addon-repo list [flags] ``` ### Examples ``` akuity argocd addon-repo list \ --organization-name= \ --instance-name= ``` ### Options ``` -h, --help help for list --instance-id string ArgoCD instance ID --instance-name string ArgoCD instance name --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd addon-repo](akuity_argocd_addon-repo.md) - Interact with ArgoCD Addon repos --- ## Akuity_argocd_addon ## akuity argocd addon Interact with ArgoCD Addons ``` akuity argocd addon [flags] ``` ### Options ``` -h, --help help for addon ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd](akuity_argocd.md) - Interact with ArgoCD resources * [akuity argocd addon cluster-customization](akuity_argocd_addon_cluster-customization.md) - Manage cluster customizations for an addon * [akuity argocd addon list](akuity_argocd_addon_list.md) - List instance addon * [akuity argocd addon sync](akuity_argocd_addon_sync.md) - Sync a addon * [akuity argocd addon update](akuity_argocd_addon_update.md) - Update a addon --- ## Akuity_argocd_addon_cluster Customization ## akuity argocd addon cluster-customization Manage cluster customizations for an addon ``` akuity argocd addon cluster-customization [flags] ``` ### Options ``` -h, --help help for cluster-customization ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd addon](akuity_argocd_addon.md) - Interact with ArgoCD Addons * [akuity argocd addon cluster-customization list](akuity_argocd_addon_cluster-customization_list.md) - List cluster customizations for an addon * [akuity argocd addon cluster-customization get](akuity_argocd_addon_cluster-customization_get.md) - Get a cluster customization by index, including its full patch * [akuity argocd addon cluster-customization add](akuity_argocd_addon_cluster-customization_add.md) - Add a cluster customization to an addon * [akuity argocd addon cluster-customization update](akuity_argocd_addon_cluster-customization_update.md) - Update a cluster customization by index * [akuity argocd addon cluster-customization delete](akuity_argocd_addon_cluster-customization_delete.md) - Delete a cluster customization by index --- ## Apply to clusters whose name is in a list ## akuity argocd addon cluster-customization add Add a cluster customization to an addon ``` akuity argocd addon cluster-customization add [flags] ``` ### Examples ``` # Apply to clusters whose name is in a list akuity argocd addon cluster-customization add \ --organization-name= \ --instance-name= \ --description="Pin image tag for prod" \ --patch-file=patch.yaml \ --name-in=prod-cluster,staging-cluster \ # Apply to clusters matching a label (env IN [prod, staging]) akuity argocd addon cluster-customization add \ --organization-name= \ --instance-name= \ --description="Override namespace" \ --patch-file=patch.yaml \ --label-in=env=prod,staging \ # Apply to all clusters akuity argocd addon cluster-customization add \ --organization-name= \ --instance-name= \ --description="Global override" \ --patch-file=patch.yaml \ --all-clusters \ ``` ### Options ``` --all-clusters Apply customization to all clusters (mutually exclusive with selector flags) --description string Description of the cluster customization (required) -h, --help help for add --instance-id string ArgoCD instance ID --instance-name string ArgoCD instance name --label-in stringArray Label filter IN: key=val1[,val2] — cluster label key matches any value (repeatable) --label-not-in stringArray Label filter NOT IN: key=val1[,val2] — cluster label key matches none of the values (repeatable) --name-in strings Name filter: cluster name IN the given comma-separated list (repeatable) --name-not-in strings Name filter: cluster name NOT IN the given comma-separated list (repeatable) --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") --patch-file string Path to a YAML or JSON file containing the patch (required) ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd addon cluster-customization](akuity_argocd_addon_cluster-customization.md) - Manage cluster customizations for an addon --- ## Akuity_argocd_addon_cluster Customization_delete ## akuity argocd addon cluster-customization delete Delete a cluster customization by index ``` akuity argocd addon cluster-customization delete [flags] ``` :::note Index shifting after deletion Cluster customizations are stored as an ordered list. When you delete an entry, all customizations with a higher index shift down by one. For example, if you delete index 0, the former index 1 becomes the new index 0. Run [`akuity argocd addon cluster-customization list`](akuity_argocd_addon_cluster-customization_list.md) after a deletion to see the updated indices before performing further operations. ::: ### Examples ``` akuity argocd addon cluster-customization delete \ --organization-name= \ --instance-name= \ ``` ### Options ``` -h, --help help for delete --instance-id string ArgoCD instance ID --instance-name string ArgoCD instance name --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd addon cluster-customization](akuity_argocd_addon_cluster-customization.md) - Manage cluster customizations for an addon --- ## Akuity_argocd_addon_cluster Customization_get ## akuity argocd addon cluster-customization get Get a cluster customization by index, including its full patch ``` akuity argocd addon cluster-customization get [flags] ``` ### Examples ``` akuity argocd addon cluster-customization get \ --organization-name= \ --instance-name= \ ``` ### Options ``` -h, --help help for get --instance-id string ArgoCD instance ID --instance-name string ArgoCD instance name --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd addon cluster-customization](akuity_argocd_addon_cluster-customization.md) - Manage cluster customizations for an addon --- ## Akuity_argocd_addon_cluster Customization_list ## akuity argocd addon cluster-customization list List cluster customizations for an addon ``` akuity argocd addon cluster-customization list [flags] ``` ### Examples ``` akuity argocd addon cluster-customization list \ --organization-name= \ --instance-name= \ ``` ### Options ``` -h, --help help for list --instance-id string ArgoCD instance ID --instance-name string ArgoCD instance name --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd addon cluster-customization](akuity_argocd_addon_cluster-customization.md) - Manage cluster customizations for an addon --- ## Update the patch file only (selector unchanged) ## akuity argocd addon cluster-customization update Update a cluster customization by index ``` akuity argocd addon cluster-customization update [flags] ``` Selector flags (`--name-in`, `--name-not-in`, `--label-in`, `--label-not-in`) **append** new filter entries to the existing cluster selector. Use `--clear-name-filters` or `--clear-label-filters` to remove existing filters before adding new ones. Use `--all-clusters` to clear the entire selector. ### Examples ``` # Update the patch file only (selector unchanged) akuity argocd addon cluster-customization update \ --organization-name= \ --instance-name= \ --patch-file=patch.yaml \ # Append a new label filter without touching existing filters akuity argocd addon cluster-customization update \ --organization-name= \ --instance-name= \ --label-not-in=env=staging \ # Replace name filters: clear existing, add new akuity argocd addon cluster-customization update \ --organization-name= \ --instance-name= \ --clear-name-filters \ --name-in=prod-cluster \ ``` ### Options ``` --all-clusters Clear the entire cluster selector, applying to all clusters --clear-label-filters Remove all existing label filters (can be combined with --label-in/--label-not-in to replace) --clear-name-filters Remove all existing name filters (can be combined with --name-in/--name-not-in to replace) --description string New description -h, --help help for update --instance-id string ArgoCD instance ID --instance-name string ArgoCD instance name --label-in stringArray Append a label IN filter: key=val1[,val2] (repeatable) --label-not-in stringArray Append a label NOT IN filter: key=val1[,val2] (repeatable) --name-in strings Append a name IN filter (comma-separated cluster names) --name-not-in strings Append a name NOT IN filter (comma-separated cluster names) --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") --patch-file string Path to a YAML or JSON file with the updated patch ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd addon cluster-customization](akuity_argocd_addon_cluster-customization.md) - Manage cluster customizations for an addon --- ## Akuity_argocd_addon_list ## akuity argocd addon list List instance addon ``` akuity argocd addon list [flags] ``` ### Examples ``` akuity argocd addon list \ --organization-name= \ --instance-name= ``` ### Options ``` -h, --help help for list --instance-id string ArgoCD instance ID --instance-name string ArgoCD instance name --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd addon](akuity_argocd_addon.md) - Interact with ArgoCD Addons --- ## Akuity_argocd_addon_sync ## akuity argocd addon sync Sync a addon ``` akuity argocd addon sync [flags] ``` ### Examples ``` akuity argocd addon sync \ --organization-name= \ --instance-name= \ ``` ### Options ``` --apply-out-of-sync-only Sync only out-of-sync resources -l, --cluster-selector.label-filters string Cluster selector label filters -n, --cluster-selector.name-filters string Cluster selector name filters --create-namespace Namespace Auto-Creation ensures that namespace specified as the application destination exists in the destination cluster. -h, --help help for sync --instance-id string ArgoCD instance ID --instance-name string ArgoCD instance name --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") -p, --propagation-policy string Specify propagation policy for deletion of application's resources. One of: foreground|background (default "foreground") --prune Allow deleting unexpected resources --prune-last Allow the ability for resource pruning to happen as a final, implicit wave of a sync operation --replace Use a kubectl create/replace instead apply --respect-ignore-diff When syncing changes, respect fields ignored by the ignoreDifferences configuration -r, --revision string Sync to a specific revision (default "HEAD") --server-side Use server-side apply while syncing the application --validate disables resource validation (equivalent to 'kubectl apply --validate=false') (default true) ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd addon](akuity_argocd_addon.md) - Interact with ArgoCD Addons --- ## Akuity_argocd_addon_update ## akuity argocd addon update Update a addon ``` akuity argocd addon update [flags] ``` ### Examples ``` akuity argocd addon update \ --organization-name= \ --instance-name= \ ``` ### Options ``` --apply-out-of-sync-only Sync only out-of-sync resources --auto-heal Set self healing when sync is automated --auto-sync Auto sync policy -l, --cluster-selector.label-filters string Cluster selector label filters -n, --cluster-selector.name-filters string Cluster selector name filters --create-namespace Namespace Auto-Creation ensures that namespace specified as the application destination exists in the destination cluster. --disable Disable addon --enable Enable addon -h, --help help for update --instance-id string ArgoCD instance ID --instance-name string ArgoCD instance name --name-template string Name tempate --namespace-template string Namespace tempate --non-cascade Perform a non cascaded deletion of all application resources --on-conflict-action string On conflict action (One of skip,overwrite) (default "overwrite") --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") --project-template string Project tempate -p, --propagation-policy string Specify propagation policy for deletion of application's resources. One of: foreground|background (default "foreground") --prune-last Allow the ability for resource pruning to happen as a final, implicit wave of a sync operation --prune-resources Set automatic pruning when sync is automated --replace Use a kubectl create/replace instead apply --respect-ignore-diff When syncing changes, respect fields ignored by the ignoreDifferences configuration --server-side Use server-side apply while syncing the application --validate disables resource validation (equivalent to 'kubectl apply --validate=false') (default true) ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd addon](akuity_argocd_addon.md) - Interact with ArgoCD Addons --- ## Akuity_argocd_apply ## akuity argocd apply Apply an Argo CD specification ``` akuity argocd apply [flags] ``` ### Options ``` -f, --filenames stringArray Path to filenames or directories of manifests -h, --help help for apply --name ArgoCD The ArgoCD instance name. The name of ArgoCD instance in the manifests takes priority over this flag. --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name --prune strings The types of resource that will be pruned if they don't exist in the manifests. The value can be 'all', 'appprojs', 'apps', 'appsets', 'clusters', 'cmps', 'repo-credentials'. ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd](akuity_argocd.md) - Interact with ArgoCD resources --- ## Akuity_argocd_cluster ## akuity argocd cluster Interact with ArgoCD clusters ``` akuity argocd cluster [flags] ``` ### Options ``` -h, --help help for cluster ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd](akuity_argocd.md) - Interact with ArgoCD resources * [akuity argocd cluster create](akuity_argocd_cluster_create.md) - Create a cluster * [akuity argocd cluster delete](akuity_argocd_cluster_delete.md) - Delete a cluster * [akuity argocd cluster get](akuity_argocd_cluster_get.md) - Get instance clusters * [akuity argocd cluster get-agent-manifests](akuity_argocd_cluster_get-agent-manifests.md) - Get cluster agent manifests * [akuity argocd cluster list](akuity_argocd_cluster_list.md) - List instance clusters * [akuity argocd cluster update](akuity_argocd_cluster_update.md) - Update a cluster * [akuity argocd cluster upgrade](akuity_argocd_cluster_upgrade.md) - Upgrade a batch of clusters to a particular version --- ## Akuity_argocd_cluster_create ## akuity argocd cluster create Create a cluster ``` akuity argocd cluster create [flags] ``` ### Examples ``` akuity argocd cluster create \ --organization-name= \ --instance-name= \ ``` ### Options ``` --agent-size string Agent size (One of small,medium,large,auto) (default "small") --akuity-custom-image-registry string Custom image registry for Akuity images --annotation stringArray Cluster annotation (e.g. --annotation 'key1' or 'key1=value1') --argoproj-custom-image-registry string Custom image registry for Argoproj images --disable-auto-update Disable automatic updates of agent components --disable-auto-upgrade Disable automatic updates of agent components (DEPRECATED: use --disable-auto-update instead) --force Disables optional cluster settings validation -h, --help help for create --instance-id string ArgoCD instance ID --instance-name string ArgoCD instance name --kustomization-path string Path to kustomization.yaml that contains cluster agent kustomization --label stringArray Cluster label (e.g. --label 'key1' or 'key1=value1') -n, --namespace string Target namespace (default "akuity") --namespace-scoped Namespace scoped cluster installation --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") --project string Argo CD Project cluster belongs to --redis-tunneling Tunnels agent redis connection instead of using a direct connection (default 'false') --state-replication Enables agent state replication (default 'false') --upsert Update if exists --version string Desired cluster agent target version ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd cluster](akuity_argocd_cluster.md) - Interact with ArgoCD clusters --- ## Akuity_argocd_cluster_delete ## akuity argocd cluster delete Delete a cluster ``` akuity argocd cluster delete [flags] ``` ### Examples ``` akuity argocd cluster delete \ --organization-name= \ --instance-name= \ ``` ### Options ``` -h, --help help for delete --instance-id string ArgoCD instance ID --instance-name string ArgoCD instance name --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd cluster](akuity_argocd_cluster.md) - Interact with ArgoCD clusters --- ## Akuity_argocd_cluster_get Agent Manifests ## akuity argocd cluster get-agent-manifests Get cluster agent manifests ``` akuity argocd cluster get-agent-manifests [flags] ``` ### Examples ``` akuity argocd cluster get-agent-manifests \ --organization-name= \ --instance-name= \ ``` ### Options ``` -h, --help help for get-agent-manifests --instance-id string ArgoCD instance ID --instance-name string ArgoCD instance name --offline-installation When set to true the agent manifests will be bundle snapshot of all Argo CD settings including applications and projects --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name --use-id Use cluster id instead of name ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd cluster](akuity_argocd_cluster.md) - Interact with ArgoCD clusters --- ## Akuity_argocd_cluster_get ## akuity argocd cluster get Get instance clusters ``` akuity argocd cluster get [flags] ``` ### Examples ``` akuity argocd cluster get \ --organization-name= \ --instance-name= \ <(optional) cluster-name or cluster-id> ``` ### Options ``` -h, --help help for get --instance-id string ArgoCD instance ID --instance-name string ArgoCD instance name --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd cluster](akuity_argocd_cluster.md) - Interact with ArgoCD clusters --- ## Akuity_argocd_cluster_list ## akuity argocd cluster list List instance clusters ``` akuity argocd cluster list [flags] ``` ### Examples ``` akuity argocd cluster list \ --organization-name= \ --instance-name= \ --label='key1=val1' ``` ### Options ``` -h, --help help for list --instance-id string ArgoCD instance ID --instance-name string ArgoCD instance name --label stringArray Cluster label (e.g. --label 'key1' or 'key1=value1') --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd cluster](akuity_argocd_cluster.md) - Interact with ArgoCD clusters --- ## Akuity_argocd_cluster_update ## akuity argocd cluster update Update a cluster ``` akuity argocd cluster update [flags] ``` ### Examples ``` akuity argocd cluster update \ --organization-name= \ --instance-name= \ ``` ### Options ``` --agent-size string Agent size (One of small,medium,large,auto) --akuity-custom-image-registry string Custom image registry for Akuity images --annotation stringArray Cluster annotation (e.g. --annotation 'key1' or 'key1=value1') --argoproj-custom-image-registry string Custom image registry for Argoproj images --disable-auto-update Disable automatic updates of agent components --disable-auto-upgrade Disable automatic updates of agent components (DEPRECATED: use --disable-auto-update instead) --force Disables optional cluster settings validation -h, --help help for update --instance-id string ArgoCD instance ID --instance-name string ArgoCD instance name --kustomization-path string Path to kustomization.yaml that contains cluster agent kustomization --label stringArray Cluster label (e.g. --label 'key1' or 'key1=value1') --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") --project string Argo CD Project cluster belongs to --version string Desired cluster agent target version ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd cluster](akuity_argocd_cluster.md) - Interact with ArgoCD clusters --- ## Akuity_argocd_cluster_upgrade ## akuity argocd cluster upgrade Upgrade a batch of clusters to a particular version ``` akuity argocd cluster upgrade [flags] ``` ### Examples ``` akuity argocd cluster upgrade \ --organization-name= \ --instance-name= \ --version= \ --clusters=,,.. ``` ### Options ``` --clusters strings List of cluster names to upgrade (e.g. --clusters name1,name2,name3) -h, --help help for upgrade --instance-id string ArgoCD instance ID --instance-name string ArgoCD instance name --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") --version string Desired cluster agent target version ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd cluster](akuity_argocd_cluster.md) - Interact with ArgoCD clusters --- ## Akuity_argocd_diff ## akuity argocd diff Diff an Argo CD specification against local files ``` akuity argocd diff [flags] ``` ### Options ``` -f, --filenames stringArray Path to filenames or directories of manifests -h, --help help for diff --ignore-errors Ignore errors when comparing files --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd](akuity_argocd.md) - Interact with ArgoCD resources --- ## Akuity_argocd_export ## akuity argocd export Export an Argo CD specification ``` akuity argocd export [flags] ``` ### Examples ``` akuity argocd export \ --organization-name= \ ``` ### Options ``` -h, --help help for export --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd](akuity_argocd.md) - Interact with ArgoCD resources --- ## Akuity_argocd_instance ## akuity argocd instance Interact with ArgoCD instances ``` akuity argocd instance [flags] ``` ### Options ``` -h, --help help for instance ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd](akuity_argocd.md) - Interact with ArgoCD resources * [akuity argocd instance create](akuity_argocd_instance_create.md) - Create an instance * [akuity argocd instance delete](akuity_argocd_instance_delete.md) - Delete an instance * [akuity argocd instance get](akuity_argocd_instance_get.md) - Get instances * [akuity argocd instance list](akuity_argocd_instance_list.md) - List instances * [akuity argocd instance update](akuity_argocd_instance_update.md) - Update an instance * [akuity argocd instance versions](akuity_argocd_instance_versions.md) - List available instance versions --- ## Akuity_argocd_instance_create ## akuity argocd instance create Create an instance ``` akuity argocd instance create [flags] ``` ### Examples ``` akuity argocd instance create \ --organization-name= \ ``` ### Options ``` --description string Instance description -h, --help help for create --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") --version string Instance version (default "stable") ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd instance](akuity_argocd_instance.md) - Interact with ArgoCD instances --- ## Akuity_argocd_instance_delete ## akuity argocd instance delete Delete an instance ``` akuity argocd instance delete [flags] ``` ### Examples ``` akuity argocd instance delete \ --organization-name= \ ``` ### Options ``` -h, --help help for delete --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd instance](akuity_argocd_instance.md) - Interact with ArgoCD instances --- ## Akuity_argocd_instance_get ## akuity argocd instance get Get instances ``` akuity argocd instance get [flags] ``` ### Examples ``` akuity argocd instance get \ --organization-name= \ <(optional) instance-name or instance-id> ``` ### Options ``` -h, --help help for get --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd instance](akuity_argocd_instance.md) - Interact with ArgoCD instances --- ## Akuity_argocd_instance_list ## akuity argocd instance list List instances ``` akuity argocd instance list [flags] ``` ### Examples ``` akuity argocd instance list \ --organization-name= ``` ### Options ``` -h, --help help for list --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd instance](akuity_argocd_instance.md) - Interact with ArgoCD instances --- ## Akuity_argocd_instance_update ## akuity argocd instance update Update an instance ``` akuity argocd instance update [flags] ``` ### Examples ``` akuity argocd instance update \ --organization-name= \ ``` ### Options ``` --description string Instance description -h, --help help for update --name string Instance name --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") --version string Instance version ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd instance](akuity_argocd_instance.md) - Interact with ArgoCD instances --- ## Akuity_argocd_instance_versions ## akuity argocd instance versions List available instance versions ``` akuity argocd instance versions [flags] ``` ### Options ``` -h, --help help for versions -o, --output string Output format. One of (json, yaml, wide) (default "wide") ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity argocd instance](akuity_argocd_instance.md) - Interact with ArgoCD instances --- ## Akuity_config ## akuity config Configure Akuity CLI ``` akuity config [flags] ``` ### Options ``` -h, --help help for config ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity](akuity.md) - * [akuity config set](akuity_config_set.md) - Set default value for the CLI --- ## Akuity_config_set ## akuity config set Set default value for the CLI ``` akuity config set [flags] ``` ### Examples ``` akuity config set \ --organization-name= ``` ### Options ``` -h, --help help for set --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity config](akuity_config.md) - Configure Akuity CLI --- ## Akuity_kargo ## akuity kargo Interact with Kargo resources ``` akuity kargo [flags] ``` ### Options ``` -h, --help help for kargo ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity](akuity.md) - * [akuity kargo agent](akuity_kargo_agent.md) - Interact with Kargo agents * [akuity kargo apply](akuity_kargo_apply.md) - Apply a Kargo instance specification * [akuity kargo diff](akuity_kargo_diff.md) - Diff a Kargo specification against local files * [akuity kargo export](akuity_kargo_export.md) - Export a Kargo specification * [akuity kargo instance](akuity_kargo_instance.md) - Interact with Kargo instances --- ## Akuity_kargo_agent ## akuity kargo agent Interact with Kargo agents ``` akuity kargo agent [flags] ``` ### Options ``` -h, --help help for agent ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity kargo](akuity_kargo.md) - Interact with Kargo resources * [akuity kargo agent create](akuity_kargo_agent_create.md) - Create an agent * [akuity kargo agent delete](akuity_kargo_agent_delete.md) - Delete an agent * [akuity kargo agent get](akuity_kargo_agent_get.md) - Get instance agents * [akuity kargo agent get-manifests](akuity_kargo_agent_get-manifests.md) - Get agent manifests * [akuity kargo agent list](akuity_kargo_agent_list.md) - List instance agents * [akuity kargo agent update](akuity_kargo_agent_update.md) - Update an agent * [akuity kargo agent upgrade](akuity_kargo_agent_upgrade.md) - Upgrade a batch of agents to a particular version --- ## Akuity_kargo_agent_create ## akuity kargo agent create Create an agent ``` akuity kargo agent create [flags] ``` ### Examples ``` akuity kargo agent create \ --organization-name= \ --instance-name= \ ``` ### Options ``` --agent-namespace string Kargo agent namespace (default "akuity") --agent-size string Agent size (One of small,medium,large) (default "small") --akuity-argocd-id string Akuity Managed ArgoCD instance ID --akuity-argocd-name string Akuity Managed ArgoCD instance name --akuity-custom-image-registry string Custom image registry for Akuity images --annotation stringArray Agent annotation (e.g. --annotation 'key1' or 'key1=value1') --argocd-namespace string Target ArgoCD Namespace --default-shard Set agent as default shard? --disable-auto-update Disable automatic updates of agent components -h, --help help for create --instance-id string Kargo instance ID --instance-name string Kargo instance name --kargo-custom-image-registry string Custom image registry for Kargo images --kustomization-path string Path to kustomization.yaml that contains kargo agent kustomization --label stringArray Agent label (e.g. --label 'key1' or 'key1=value1') --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") --self-hosted[=false] Is the Kargo agent self-hosted? --upsert Update if exists --version string Target version ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity kargo agent](akuity_kargo_agent.md) - Interact with Kargo agents --- ## Akuity_kargo_agent_delete ## akuity kargo agent delete Delete an agent ``` akuity kargo agent delete [flags] ``` ### Examples ``` akuity kargo agent delete \ --organization-name= \ --instance-name= \ ``` ### Options ``` -h, --help help for delete --instance-id string Kargo instance ID --instance-name string Kargo instance name --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity kargo agent](akuity_kargo_agent.md) - Interact with Kargo agents --- ## Akuity_kargo_agent_get Manifests ## akuity kargo agent get-manifests Get agent manifests ``` akuity kargo agent get-manifests [flags] ``` ### Examples ``` akuity kargo agent get-manifests \ --organization-name= \ --instance-name= \ ``` ### Options ``` -h, --help help for get-manifests --instance-id string Kargo instance ID --instance-name string Kargo instance name --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity kargo agent](akuity_kargo_agent.md) - Interact with Kargo agents --- ## Akuity_kargo_agent_get ## akuity kargo agent get Get instance agents ``` akuity kargo agent get [flags] ``` ### Examples ``` akuity kargo agent get \ --organization-name= \ --instance-name= \ <(optional) agent-name or agent-id> ``` ### Options ``` -h, --help help for get --instance-id string Kargo instance ID --instance-name string Kargo instance name --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity kargo agent](akuity_kargo_agent.md) - Interact with Kargo agents --- ## Akuity_kargo_agent_list ## akuity kargo agent list List instance agents ``` akuity kargo agent list [flags] ``` ### Examples ``` akuity kargo agent list \ --organization-name= \ --instance-name= \ --label='key1=val1' ``` ### Options ``` -h, --help help for list --instance-id string Kargo instance ID --instance-name string Kargo instance name --label stringArray Agent label (e.g. --label 'key1' or 'key1=value1') --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity kargo agent](akuity_kargo_agent.md) - Interact with Kargo agents --- ## Akuity_kargo_agent_update ## akuity kargo agent update Update an agent ``` akuity kargo agent update [flags] ``` ### Examples ``` akuity kargo agent update \ --organization-name= \ --instance-name= \ ``` ### Options ``` --agent-size string Agent size (One of small,medium,large) --akuity-custom-image-registry string Custom image registry for Akuity images --annotation stringArray Agent annotation (e.g. --annotation 'key1' or 'key1=value1') --default-shard Set agent as default shard? --disable-auto-update Disable automatic updates of agent components -h, --help help for update --instance-id string Kargo instance ID --instance-name string Kargo instance name --kargo-custom-image-registry string Custom image registry for Kargo images --kustomization-path string Path to kustomization.yaml that contains kargo agent kustomization --label stringArray Agent label (e.g. --label 'key1' or 'key1=value1') --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") --version string Desired kargo agent target version ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity kargo agent](akuity_kargo_agent.md) - Interact with Kargo agents --- ## Akuity_kargo_agent_upgrade ## akuity kargo agent upgrade Upgrade a batch of agents to a particular version ``` akuity kargo agent upgrade [flags] ``` ### Examples ``` akuity kargo agent upgrade \ --organization-name= \ --instance-name= \ --version= \ --agents=,,.. ``` ### Options ``` --agents strings List of agent names to upgrade (e.g. --agents name1,name2,name3) -h, --help help for upgrade --instance-id string Kargo instance ID --instance-name string Kargo instance name --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") --version string Desired kargo agent target version ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity kargo agent](akuity_kargo_agent.md) - Interact with Kargo agents --- ## Akuity_kargo_apply ## akuity kargo apply Apply a Kargo instance specification ``` akuity kargo apply [flags] ``` ### Options ``` -f, --filenames stringArray Path to filenames or directories of manifests -h, --help help for apply --name Kargo The Kargo instance name. The name of Kargo instance in the manifests takes priority over this flag. --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name --prune strings The types of resource that will be pruned if they don't exist in the manifests. The value can be 'agents', 'all', 'analysis-templates', 'cluster-message-channels', 'cluster-promotion_tasks', 'message-channels', 'project-configs', 'projects', 'promotion-tasks', 'repo-credentials', 'stages', 'warehouses'. ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity kargo](akuity_kargo.md) - Interact with Kargo resources --- ## Akuity_kargo_diff ## akuity kargo diff Diff a Kargo specification against local files ``` akuity kargo diff [flags] ``` ### Options ``` -f, --filenames stringArray Path to filenames or directories of manifests -h, --help help for diff --ignore-errors Ignore errors when comparing files --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity kargo](akuity_kargo.md) - Interact with Kargo resources --- ## Akuity_kargo_export ## akuity kargo export Export a Kargo specification ``` akuity kargo export [flags] ``` ### Examples ``` akuity kargo export \ --organization-name= \ ``` ### Options ``` -h, --help help for export --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity kargo](akuity_kargo.md) - Interact with Kargo resources --- ## Akuity_kargo_instance ## akuity kargo instance Interact with Kargo instances ``` akuity kargo instance [flags] ``` ### Options ``` -h, --help help for instance ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity kargo](akuity_kargo.md) - Interact with Kargo resources * [akuity kargo instance create](akuity_kargo_instance_create.md) - Create an instance * [akuity kargo instance delete](akuity_kargo_instance_delete.md) - Delete an instance * [akuity kargo instance get](akuity_kargo_instance_get.md) - Get instances * [akuity kargo instance list](akuity_kargo_instance_list.md) - List instances * [akuity kargo instance update](akuity_kargo_instance_update.md) - Update an instance * [akuity kargo instance versions](akuity_kargo_instance_versions.md) - List available instance versions --- ## Akuity_kargo_instance_create ## akuity kargo instance create Create an instance ``` akuity kargo instance create [flags] ``` ### Examples ``` akuity kargo instance create \ --organization-name= \ ``` ### Options ``` --description string Instance description -h, --help help for create --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") --version string Instance version (default "stable") ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity kargo instance](akuity_kargo_instance.md) - Interact with Kargo instances --- ## Akuity_kargo_instance_delete ## akuity kargo instance delete Delete an instance ``` akuity kargo instance delete [flags] ``` ### Examples ``` akuity kargo instance delete \ --organization-name= \ ``` ### Options ``` -h, --help help for delete --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity kargo instance](akuity_kargo_instance.md) - Interact with Kargo instances --- ## Akuity_kargo_instance_get ## akuity kargo instance get Get instances ``` akuity kargo instance get [flags] ``` ### Examples ``` akuity kargo instance get \ --organization-name= \ <(optional) instance-name or instance-id> ``` ### Options ``` -h, --help help for get --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity kargo instance](akuity_kargo_instance.md) - Interact with Kargo instances --- ## Akuity_kargo_instance_list ## akuity kargo instance list List instances ``` akuity kargo instance list [flags] ``` ### Examples ``` akuity kargo instance list \ --organization-name= ``` ### Options ``` -h, --help help for list --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity kargo instance](akuity_kargo_instance.md) - Interact with Kargo instances --- ## Akuity_kargo_instance_update ## akuity kargo instance update Update an instance ``` akuity kargo instance update [flags] ``` ### Examples ``` akuity kargo instance update \ --organization-name= \ ``` ### Options ``` --description string Instance description -h, --help help for update --org-id string Alias for organization-id --org-name string Alias for organization-name --organization-id string Akuity cloud organization ID --organization-name string Akuity cloud organization name -o, --output string Output format. One of (json, yaml, wide) (default "wide") --version string Instance version ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity kargo instance](akuity_kargo_instance.md) - Interact with Kargo instances --- ## Akuity_kargo_instance_versions ## akuity kargo instance versions List available instance versions ``` akuity kargo instance versions [flags] ``` ### Options ``` -h, --help help for versions -o, --output string Output format. One of (json, yaml, wide) (default "wide") ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity kargo instance](akuity_kargo_instance.md) - Interact with Kargo instances --- ## Akuity_login ## akuity login Authenticate with an Akuity server ``` akuity login [flags] ``` ### Options ``` -h, --help help for login ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity](akuity.md) - --- ## Akuity_logout ## akuity logout Remove authentication for an Akuity server ``` akuity logout [flags] ``` ### Options ``` -h, --help help for logout ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity](akuity.md) - --- ## Akuity_organization ## akuity organization Interact with Akuity organizations ``` akuity organization [flags] ``` ### Options ``` -h, --help help for organization ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity](akuity.md) - * [akuity organization get](akuity_organization_get.md) - Get organizations * [akuity organization list](akuity_organization_list.md) - List organizations --- ## Akuity_organization_get ## akuity organization get Get organizations ``` akuity organization get [flags] ``` ### Examples ``` akuity organization get \ <(optional) organization-name or organization-id> ``` ### Options ``` -h, --help help for get -o, --output string Output format. One of (json, yaml, wide) (default "wide") ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity organization](akuity_organization.md) - Interact with Akuity organizations --- ## Akuity_organization_list ## akuity organization list List organizations ``` akuity organization list [flags] ``` ### Examples ``` akuity organization list ``` ### Options ``` -h, --help help for list ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity organization](akuity_organization.md) - Interact with Akuity organizations --- ## Akuity_version ## akuity version Display the version of the Akuity CLI ``` akuity version [flags] ``` ### Options ``` -h, --help help for version --short Print short version only ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity](akuity.md) - --- ## Akuity_whoami ## akuity whoami Display information about the currently authenticated user ### Synopsis Display information about the currently authenticated user, including their username and expiration time of the access token. ``` akuity whoami [flags] ``` ### Options ``` -h, --help help for whoami ``` ### Options inherited from parent commands ``` --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity --no-color Disable colored output (default true) --server string The server url of the Akuity cloud (default "https://akuity.cloud") ``` ### SEE ALSO * [akuity](akuity.md) - --- ## CLI Akuity CLI is a command line interface for the Akuity Platform. See [CLI Getting Started](/akuity-portal/automation) to learn how to install and use it. --- ## Crossplane Provider Manage Akuity Platform resources as Kubernetes-native custom resources with the [Akuity Crossplane provider](https://marketplace.upbound.io/providers/akuity/provider-crossplane-akuity/latest). | Resource | Link | | --- | --- | | Documentation, resources & upgrade notes | https://marketplace.upbound.io/providers/akuity/provider-crossplane-akuity | | Source code | https://github.com/akuity/provider-crossplane-akuity | | Examples | https://github.com/akuity/provider-crossplane-akuity/tree/main/examples | The [marketplace documentation](https://marketplace.upbound.io/providers/akuity/provider-crossplane-akuity/latest?tab=documentation) covers installation, provider configuration, every managed resource, and upgrade notes. ## Example Configure a `ProviderConfig` that every managed resource references: ```yaml apiVersion: akuity.crossplane.io/v1alpha1 kind: ProviderConfig metadata: name: akuity spec: organizationId: credentialsSecretRef: namespace: crossplane-system name: akuity-provider-secret key: credentials ``` The referenced Secret holds JSON with `apiKeyId` and `apiKeySecret`. The provider targets the US region (`https://akuity.cloud`) by default; EU customers should set `spec.serverUrl` to `https://eu.akuity.cloud`. ## FAQ **Do I need an Akuity API key?** Yes. Create one (see [API Keys](/akuity-portal/organizations/api-keys)) and store its `apiKeyId` and `apiKeySecret` as JSON in the Secret referenced by the `ProviderConfig` above. **Where do I report a bug or request a feature?** Open an issue at https://github.com/akuity/provider-crossplane-akuity/issues. --- ## Argo CD Spec ```yaml apiVersion: argocd.akuity.io/v1alpha1 kind: ArgoCD metadata: name: test spec: description: "instance description" instanceSpec: appSetDelegate: managedCluster: clusterName: laptop assistantExtensionEnabled: true auditExtensionEnabled: true backendIpAllowListEnabled: true clusterCustomizationDefaults: autoUpgradeDisabled: false appReplication: true redisTunneling: true kustomization: images: - name: quay.io/akuity/agent newName: my-company.io/akuity/agent - name: quay.io/argoproj/argocd newName: my-company.io/argoproj/argocd declarativeManagementEnabled: true secrets: sources: - clusters: matchExpressions: - key: test-label operator: In values: - true secrets: {} extensions: - id: argo_rollouts version: v0.3.7 imageUpdaterDelegate: managedCluster: clusterName: laptop imageUpdaterEnabled: true ipAllowList: - description: test ip: 192.0.0.1/32 appsetPolicy: policy: sync overridePolicy: false repoServerDelegate: managedCluster: clusterName: laptop subdomain: my-subdomain syncHistoryExtensionEnabled: true version: v3.4.2-ak.87 ``` --- ## Cluster Spec ```yaml apiVersion: argocd.akuity.io/v1alpha1 kind: Cluster metadata: name: test-cluster-update namespace: test labels: test-label: "true" annotations: test-annotation: "false" spec: namespaceScoped: true description: test-inst data: size: small autoUpgradeDisabled: true appReplication: true targetVersion: 0.4.1 kustomization: apiVersion: kustomize.config.k8s.io/v1beta1 kind: Kustomization resources: - test.yaml datadogAnnotationsEnabled: false eksAddonEnabled: false multiClusterK8sDashboardEnabled: true redisTunneling: false argocdNotificationsSettings: inClusterSettings: false autoscalerConfig: applicationController: resourceMaximum: cpu: "6" mem: 16Gi resourceMinimum: cpu: "2" mem: 4Gi repoServer: replicaMaximum: 10 replicaMinimum: 2 resourceMaximum: cpu: "4" mem: 6Gi resourceMinimum: cpu: "1" mem: 1Gi ``` --- ## ConfigManagementPlugin Spec ```yaml apiVersion: argoproj.io/v1alpha1 kind: ConfigManagementPlugin metadata: annotations: akuity.io/enabled: "true" akuity.io/image: ghcr.io/travisghansen/argo-cd-helmfile:v0.3.6 name: helmfile spec: discover: fileName: helmfile.yaml find: {} generate: args: - generate command: - argo-cd-helmfile.sh init: args: - init command: - argo-cd-helmfile.sh parameters: dynamic: args: - parameters command: - argo-cd-helmfile.sh ``` --- ## ConfigMap Specs ## argocd-cm ```yaml apiVersion: v1 kind: ConfigMap metadata: name: argocd-cm data: users.anonymous.enabled: "false" kustomize.buildOptions: --load_restrictor none admin.enabled: "false" accounts.alice: apiKey, login accounts.alice.enabled: "true" accounts.bob: login accounts.bob.enabled: "false" application.links: '[{"title":"Datadog Events","url":"https://us3.datadoghq.com/event/explorer?query=kube_cluster_name%3A{{.application.spec.destination.name}}%20kube_namespace%3A{{.application.spec.destination.namespace}}%20source%3Akubernetes"}]' exec.enabled: "false" helm.enabled: "true" kustomize.enabled: "true" resource.links: '[{"title":"Datadog Logs","url":"https://us3.datadoghq.com/logs?query=pod_name%3A{{.resource.metadata.name}}","if":"resource.kind == \"Pod\""}]' dex.config: | connectors: # GitHub example - type: github id: github name: GitHub config: clientID: aabbccddeeff00112233 clientSecret: $dex.github.clientSecret orgs: - name: your-github-org resource.customizations.health.certmanager.k8s.io_Certificate: | hs = {} hs.status = "Progressing" hs.message = "Waiting for certificate" return hs ``` ## argocd-rbac-cm ```yaml apiVersion: v1 kind: ConfigMap metadata: name: argocd-rbac-cm data: policy.default: role:readonly policy.csv: | p, role:org-admin, applications, *, */*, allow p, role:org-admin, clusters, get, *, allow g, your-github-org:your-team, role:org-admin ``` ## argocd-notification-cm ```yaml apiVersion: v1 kind: ConfigMap metadata: name: argocd-notifications-cm data: trigger.on-sync-status-unknown: | - when: app.status.sync.status == 'Unknown' send: [my-custom-template] template.my-custom-template: | message: | Application details: {{.context.argocdUrl}}/applications/{{.app.metadata.name}}. defaultTriggers: | - on-sync-status-unknown ``` ## argocd-image-updater-config ```yaml apiVersion: v1 kind: ConfigMap metadata: name: argocd-image-updater-config data: registries.conf: |- registries: - prefix: docker.io name: Docker api_url: https://registry-1.docker.io credentials: secret:argocd/argocd-image-updater-secret#my-docker-credentials git.email: akuity@akuity.io git.user: akuity ``` ## argocd-image-updater-ssh-config ```yaml apiVersion: v1 kind: ConfigMap metadata: name: argocd-image-updater-ssh-config data: config: |- Host * PubkeyAcceptedAlgorithms +ssh-rsa HostkeyAlgorithms +ssh-rsa ``` ## argocd-ssh-known-hosts-cm ```yaml apiVersion: v1 kind: ConfigMap metadata: labels: app.kubernetes.io/name: argocd-ssh-known-hosts-cm app.kubernetes.io/part-of: argocd name: argocd-ssh-known-hosts-cm data: ssh_known_hosts: | bitbucket.org ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAubiN81eDcafrgMeLzaFPsw2kNvEcqTKl/VqLat/MaB33pZy0y3rJZtnqwR2qOOvbwKZYKiEO1O6VqNEBxKvJJelCq0dTXWT5pbO2gDXC6h6QDXCaHo6pOHGPUy+YBaGQRGuSusMEASYiWunYN0vCAI8QaXnWMXNMdFP3jHAJH0eDsoiGnLPBlBp4TNm6rYI74nMzgz3B9IikW4WVK+dc8KZJZWYjAuORU3jc1c/NPskD2ASinf8v3xnfXeukU0sJ5N6m5E8VLjObPEO+mN2t/FZTMZLiFqPWc/ALSqnMnnhwrNi2rbfg/rd/IpL8Le3pSBne8+seeFVBoGqzHM9yXw== github.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndNxQowgcQnjshcLrqPEiiphnt+VTTvDP6mHBL9j1aNUkY4Ue1gvwnGLVlOhGeYrnZaMgRK6+PKCUXaDbC7qtbW8gIkhL7aGCsOr/C56SJMy/BCZfxd1nWzAOxSDPgVsmerOBYfNqltV9/hWCqBywINIR+5dIg6JTJ72pcEpEjcYgXkE2YEFXV1JHnsKgbLWNlhScqb2UmyRkQyytRLtL+38TGxkxCflmO+5Z8CSSNY7GidjMIZ7Q4zMjA2n1nGrlTDkzwDCsw+wqFPGQA179cnfGWOWRVruj16z6XyvxvjJwbz0wQZ75XK5tKSb7FNyeIEs4TT4jk+S4dhPeAUC5y+bDYirYgM4GC7uEnztnZyaVWQ7B381AK4Qdrwt51ZqExKbQpTUNn+EjqoTwvqNj4kqx5QUCI0ThS/YkOxJCXmPUWZbhjpCg56i+2aB6CmK2JGhn57K5mj0MNdBXA4/WnwH6XoPWJzK5Nyu2zB3nAZp+S5hpQs+p1vN1/wsjk= gitlab.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBFSMqzJeV9rUzU4kWitGjeR4PWSa29SPqJ1fVkhtj3Hw9xjLVXVYrU9QlYWrOLXBpQ6KWjbjTDTdDkoohFzgbEY= gitlab.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAfuCHKVTjquxvt6CM6tdG4SLp1Btn/nOeHHE5UOzRdf gitlab.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCsj2bNKTBSpIYDEGk9KxsGh3mySTRgMtXL583qmBpzeQ+jqCMRgBqB98u3z++J1sKlXHWfM9dyhSevkMwSbhoR8XIq/U0tCNyokEi/ueaBMCvbcTHhO7FcwzY92WK4Yt0aGROY5qX2UKSeOvuP4D6TPqKF1onrSzH9bx9XUf2lEdWT/ia1NEKjunUqu1xOB/StKDHMoX4/OKyIzuS0q/T1zOATthvasJFoPrAjkohTyaDUz2LN5JoH839hViyEG82yB+MjcFV5MU3N1l1QL3cVUCh93xSaua1N85qivl+siMkPGbO5xR/En4iEY6K2XPASUEMaieWVNTRCtJ4S8H+9 ssh.dev.azure.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC7Hr1oTWqNqOlzGJOfGJ4NakVyIzf1rXYd4d7wo6jBlkLvCA4odBlL0mDUyZ0/QUfTTqeu+tm22gOsv+VrVTMk6vwRU75gY/y9ut5Mb3bR5BV58dKXyq9A9UeB5Cakehn5Zgm6x1mKoVyf+FFn26iYqXJRgzIZZcZ5V6hrE0Qg39kZm4az48o0AUbf6Sp4SLdvnuMa2sVNwHBboS7EJkm57XQPVU3/QpyNLHbWDdzwtrlS+ez30S3AdYhLKEOxAG8weOnyrtLJAUen9mTkol8oII1edf7mWWbWVf0nBmly21+nZcmCTISQBtdcyPaEno7fFQMDD26/s0lfKob4Kw8H vs-ssh.visualstudio.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC7Hr1oTWqNqOlzGJOfGJ4NakVyIzf1rXYd4d7wo6jBlkLvCA4odBlL0mDUyZ0/QUfTTqeu+tm22gOsv+VrVTMk6vwRU75gY/y9ut5Mb3bR5BV58dKXyq9A9UeB5Cakehn5Zgm6x1mKoVyf+FFn26iYqXJRgzIZZcZ5V6hrE0Qg39kZm4az48o0AUbf6Sp4SLdvnuMa2sVNwHBboS7EJkm57XQPVU3/QpyNLHbWDdzwtrlS+ez30S3AdYhLKEOxAG8weOnyrtLJAUen9mTkol8oII1edf7mWWbWVf0nBmly21+nZcmCTISQBtdcyPaEno7fFQMDD26/s0lfKob4Kw8H github.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEmKSENjQEezOmxkZMy7opKgwFB9nkt5YRrYMjNuG5N87uRgg6CLrbo5wAdT/y6v0mKV0U2w0WZ2YB/++Tpockg= github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl ``` ## argocd-tls-certs-cm ```yaml apiVersion: v1 kind: ConfigMap metadata: name: argocd-tls-certs-cm namespace: argocd labels: app.kubernetes.io/name: argocd-tls-certs-cm app.kubernetes.io/part-of: argocd data: server.example.com: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- ``` --- ## Argo CD Instance Specs Argo CD Instance Specs can be used declaratively to apply specs to a Kargo instance on the Akuity Platform. See [akuity argocd apply](/akuity-portal/reference/cli/akuity_argocd_apply) to learn how use it. --- ## Secret Specs ## Controller Secrets ### argocd-secret ```yaml apiVersion: v1 kind: Secret metadata: name: argocd-secret type: Opaque stringData: dex.github.clientSecret: my-github-oidc-secret webhook.github.secret: shhhh! it's a github secret ``` ### argocd-notifications-secret ```yaml apiVersion: v1 kind: Secret metadata: name: argocd-notifications-secret type: Opaque stringData: email-username: test@argoproj.io email-password: password ``` ### argocd-image-updater-secret ```yaml apiVersion: v1 kind: Secret metadata: name: argocd-image-updater-secret type: Opaque stringData: my-docker-credentials: abcd1234 ``` ### application-set-secret ```yaml apiVersion: v1 kind: Secret metadata: name: application-set-secret type: Opaque stringData: my-appset-secret: xyz456 ``` ## Repository Secrets :::info All repository credentials are required to have a prefix of `repo-` for the name of the secret. ::: ### repo-argoproj-https-creds ```yaml apiVersion: v1 kind: Secret metadata: name: repo-argoproj-https-creds namespace: argocd labels: argocd.argoproj.io/secret-type: repo-creds stringData: url: https://github.com/argoproj type: helm password: my-password username: my-username ``` ### repo-my-private-https-repo ```yaml apiVersion: v1 kind: Secret metadata: name: repo-my-private-https-repo namespace: argocd labels: argocd.argoproj.io/secret-type: repository stringData: url: https://github.com/argoproj/argocd-example-apps password: my-password username: my-username insecure: "true" forceHttpBasicAuth: "true" enableLfs: "true" ``` ### repo-my-private-ssh-repo ```yaml apiVersion: v1 kind: Secret metadata: name: repo-my-private-ssh-repo namespace: argocd labels: argocd.argoproj.io/secret-type: repository stringData: url: ssh://git@github.com/argoproj/argocd-example-apps sshPrivateKey: | -----BEGIN OPENSSH PRIVATE KEY----- ... -----END OPENSSH PRIVATE KEY----- insecure: "true" enableLfs: "true" ``` --- ## Argo CD Custom Resources ## Application ```yaml apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: helm-guestbook spec: destination: namespace: helm-guestbook server: http://cluster-test:8001 project: default source: path: helm-guestbook repoURL: https://github.com/argoproj/argocd-example-apps targetRevision: HEAD ``` ## ApplicationSet ```yaml apiVersion: argoproj.io/v1alpha1 kind: ApplicationSet metadata: name: guestbook spec: generators: - list: elements: - cluster: test url: http://cluster-test:8001 - cluster: stage url: http://cluster-stage:8001 template: metadata: name: '{{cluster}}-guestbook' spec: project: default source: path: helm-guestbook repoURL: https://github.com/argoproj/argocd-example-apps targetRevision: HEAD destination: server: '{{url}}' namespace: guestbook ``` ## AppProject ```yaml apiVersion: argoproj.io/v1alpha1 kind: AppProject metadata: name: my-project spec: description: Example Project ``` --- ## Kargo Instance Specs Kargo Instance Specs can be used declaratively to apply specs to a Kargo instance on the Akuity Platform. See [akuity kargo apply](/akuity-portal/reference/cli/akuity_kargo_apply) to learn how use it. --- ## Kargo Agent Spec ```yaml apiVersion: kargo.akuity.io/v1alpha1 kind: KargoAgent metadata: annotations: app: kargo labels: app: kargo name: test-agent namespace: test-namespace spec: description: test-description data: # Set akuityManaged to false if the agent is self-hosted, and this should not be changed anymore once it is set. akuityManaged: false # this needs to be the ArgoCD instance ID, and once it is set, it should not be changed. remoteArgocd: "" # this can be configured in self-hosted mode, if the remote argocd is not provided, and if this is provided, the remote argocd will be ignored. argocdNamespace: argocd # configure this based on the situation of self-hosted or not. autoUpgradeDisabled: true kustomization: apiVersion: kustomize.config.k8s.io/v1beta1 images: - name: ghcr.io/akuity/kargo newName: quay.io/fake/kargo - name: quay.io/akuityio/argo-rollouts newName: quay.io/fake/argo-rollouts - name: quay.io/akuity/agent newName: quay.io/fake/agent kind: Kustomization size: medium targetVersion: 0.5.52 ``` --- ## Kargo Configmap Spec ```yaml apiVersion: v1 data: adminAccountEnabled: "true" adminAccountTokenTtl: 24h kind: ConfigMap metadata: labels: app.kubernetes.io/component: api app.kubernetes.io/instance: kargo app.kubernetes.io/name: kargo name: kargo-cm ``` --- ## Kargo Secret Spec ```yaml apiVersion: v1 data: adminAccountPasswordHash: $2a$10$wThs/VVwx5Tbygkk5Rzbv.V8hR8JYYmRdBiGjue9pd0YcEXl7.Kn. kind: Secret metadata: labels: app.kubernetes.io/component: api app.kubernetes.io/instance: kargo app.kubernetes.io/name: kargo name: kargo-secret ``` --- ## Kargo Spec ```yaml apiVersion: kargo.akuity.io/v1alpha1 kind: Kargo metadata: name: test spec: description: test-description # only set one of fqdn and subdomain fqdn: test.akuity.kargo.io subdomain: "" kargoInstanceSpec: agentCustomizationDefaults: kustomization: apiVersion: kustomize.config.k8s.io/v1beta1 images: - name: ghcr.io/akuity/kargo newName: quay.io/fake/kargo - name: quay.io/akuityio/argo-rollouts newName: quay.io/fake/argo-rollouts - name: quay.io/akuity/agent newName: quay.io/fake/agent kind: Kustomization backendIpAllowListEnabled: true secrets: sources: - clusters: matchExpressions: - key: app operator: In values: - kargo secrets: {} globalCredentialsNs: - test1 - test2 globalServiceAccountNs: - test3 - test4 ipAllowList: - description: test-ip ip: 77.77.77.77 - description: test ip ip: 88.88.88.88 oidcConfig: enabled: true dexEnabled: true # dexConfig should be set only if dexEnabled is true dexConfig: | connectors: # GitHub example - type: github id: github name: GitHub config: clientID: aabbccddeeff00112233 clientSecret: $GITHUB_CLIENT_SECRET orgs: - name: your-github-org teams: - red-team adminAccount: claims: email: values: - admin@akuity.io groups: values: - admin-group@akuity.io sub: values: - admin-sub@akuity.io viewerAccount: claims: email: values: - viewer@akuity.io groups: values: - viewer-group@akuity.io sub: values: - viewer-sub@akuity.io # cliClientId, clientId, dexConfigSecret, additionalScopes, issuerUrl are oidc configs, and should be set only if dexEnabled is false cliClientId: "" clientId: "" dexConfigSecret: null additionalScopes: null issuerUrl: "" version: v1.10.4-ak.0 ``` --- ## Kargo Custom Resources ## Project ```yaml apiVersion: kargo.akuity.io/v1alpha1 kind: Project metadata: name: kargo-demo-11 spec: promotionPolicies: - stage: test autoPromotionEnabled: true - stage: uat autoPromotionEnabled: true - stage: prod autoPromotionEnabled: false ``` ## Warehouse ```yaml apiVersion: kargo.akuity.io/v1alpha1 kind: Warehouse metadata: name: kargo-demo namespace: kargo-demo-11 spec: subscriptions: - git: repoURL: https://github.com//kargo-demo-gitops.git branch: new-helm - image: repoURL: public.ecr.aws/nginx/nginx semverConstraint: ^1.24.0 ``` ## Stage ```yaml apiVersion: kargo.akuity.io/v1alpha1 kind: Stage metadata: name: test namespace: kargo-demo-11 spec: requestedFreight: - origin: kind: Warehouse name: kargo-demo sources: direct: true promotionTemplate: spec: vars: - name: gitRepo value: https://github.com//kargo-demo-gitops.git - name: targetBranch value: 11/stage/${{ ctx.stage }} - name: outPath value: ./out steps: - task: name: base-promo-process as: base - uses: git-push config: path: ${{ vars.outPath }} targetBranch: ${{ vars.targetBranch }} - uses: argocd-update config: apps: - name: ${{ ctx.project }}-${{ ctx.stage }} sources: - repoURL: ${{ vars.gitRepo }} desiredRevision: ${{ outputs.base.commit }} verification: analysisTemplates: - name: kargo-demo ``` ## AnalysisTemplate ```yaml apiVersion: argoproj.io/v1alpha1 kind: AnalysisTemplate metadata: name: kargo-demo namespace: kargo-demo-11 spec: metrics: - name: test provider: job: metadata: spec: backoffLimit: 1 template: spec: containers: - name: test image: alpine:latest command: - sleep - "20" restartPolicy: Never ``` ## PromotionTask ```yaml apiVersion: kargo.akuity.io/v1alpha1 kind: PromotionTask metadata: name: base-promo-process namespace: kargo-demo-11 spec: vars: - name: gitRepo - name: targetBranch - name: outPath - name: imageRepo value: public.ecr.aws/nginx/nginx steps: - uses: git-clone config: repoURL: ${{ vars.gitRepo }} checkout: - commit: ${{ commitFrom(vars.gitRepo).ID }} path: ./src - branch: ${{ vars.targetBranch }} create: true path: ${{ vars.outPath }} - uses: git-clear config: path: ${{ vars.outPath }} - uses: yaml-update as: update-image config: path: ./src/charts/kargo-demo/values.yaml updates: - key: image.name value: ${{ vars.imageRepo }}:${{ imageFrom(vars.imageRepo).Tag }} - uses: helm-template config: path: ./src/charts/kargo-demo releaseName: kargo-demo valuesFiles: - ./src/charts/kargo-demo/stages/${{ ctx.stage }}/values.yaml outPath: ${{ vars.outPath }} - uses: git-commit as: commit config: path: ${{ vars.outPath }} messageFromSteps: - update-image - uses: compose-output config: commit: ${{ task.outputs.commit.commit }} ``` --- ## Declarative Specs The Akuity CLI can be used to apply declarative specs to the Akuity Platform. See [akuity argocd apply](/akuity-portal/reference/cli/akuity_argocd_apply) and [akuity kargo apply](/akuity-portal/reference/cli/akuity_kargo_apply) to learn how to use them. ### ArgoCD Example: First create your ArgoCD spec then apply it with the following command: `akuity argocd apply -f argocd-spec.yaml --organization-name ` ```yaml apiVersion: argocd.akuity.io/v1alpha1 kind: ArgoCD metadata: name: declarative-specs spec: description: "" instanceSpec: clusterCustomizationDefaults: kustomization: {} declarativeManagementEnabled: true subdomain: 5b0rw97jfpseuaiz shard: "" version: v2.8.0 ``` | File | Manageable via Argo CD | Manageable via Declarative Specs | |-----------------------------------------------------------------------------------------------------------------------------------------|------------------------|------------------------------------------------------------------------------------| | [`argocd-cm.yaml`](https://github.com/argoproj/argo-cd/blob/master/docs/operator-manual/argocd-cm.yaml) | No | Yes | | [`argocd-rbac-cm.yaml`](https://github.com/argoproj/argo-cd/blob/master/docs/operator-manual/argocd-rbac-cm.yaml) | No | Yes | | [`argocd-secret.yaml`](https://github.com/argoproj/argo-cd/blob/master/docs/operator-manual/argocd-secret.yaml) | No | Yes | | [`argocd-ssh-known-hosts-cm.yaml`](https://github.com/argoproj/argo-cd/blob/master/docs/operator-manual/argocd-ssh-known-hosts-cm.yaml) | Yes | Yes | | [`argocd-tls-certs-cm.yaml`](https://github.com/argoproj/argo-cd/blob/master/docs/operator-manual/argocd-tls-certs-cm.yaml) | Yes | Yes | | [`single repo credentials`](https://github.com/argoproj/argo-cd/blob/master/docs/operator-manual/argocd-repositories.yaml) | Yes | Yes | | [`repo template credentials`](https://github.com/argoproj/argo-cd/blob/master/docs/operator-manual/argocd-repo-creds.yaml) | Yes | Yes | | [`application.yaml`](https://github.com/argoproj/argo-cd/blob/master/docs/operator-manual/application.yaml) | Yes | Yes | | [`project.yaml`](https://github.com/argoproj/argo-cd/blob/master/docs/operator-manual/project.yaml) | Yes | Yes | | [`applicationset.yaml`](https://github.com/argoproj/argo-cd/blob/master/docs/operator-manual/applicationset.yaml) | Yes | Yes | ### Kargo Example: First create your Kargo spec then apply it with the following command: `akuity kargo apply -f kargo-spec.yaml --organization-name ` ```yaml apiVersion: kargo.akuity.io/v1alpha1 kind: Kargo metadata: name: test-2 spec: description: test-description version: v1.2.2 ``` There is a more comprehensive example [here](./20-kargo-instance-specs/kargo-spec.md). | File | Manageable via Kargo | Manageable via Declarative Specs | |-----------------------------------------------------------------------|----------------------|---------------------------------------| | [`kargo-cm.yaml`](./20-kargo-instance-specs/kargo-cm-spec.md) | No | Yes | | [`kargo-secret.yaml`](./20-kargo-instance-specs/kargo-secret-spec.md) | No | Yes | --- ## Reference --- ## Notification Webhook Schema ### AgentHealthEvent {#akuity-notifications-webhook-v1-AgentHealthEvent} `AgentHealthEvent` contains metadata for an agent health event. | Field | Type | Description | | ----- | ---- | ----------- | | instance_id | string | The instance ID. | | instance_name | string | The instance name. | | cluster_id | string | The cluster ID. | | cluster_name | string | The cluster name. | | status | string | The agent status: "connected" or "disconnected". | | timestamp | google.protobuf.Timestamp | The time the status change occurred. | | kargo | bool | Whether this is a Kargo agent (true) or Argo CD cluster (false). | ### AuditEvent {#akuity-notifications-webhook-v1-AuditEvent} `AuditEvent` contains metadata for an audit event. | Field | Type | Description | | ----- | ---- | ----------- | | timestamp | string | The time the event was triggered. | | action | string | The action that was performed. | | actor | [AuditEvent.EventAuditActor](#akuity-notifications-webhook-v1-AuditEvent-EventAuditActor) | The actor that triggered the event. | | object | [AuditEvent.EventAuditObject](#akuity-notifications-webhook-v1-AuditEvent-EventAuditObject) | The object that was acted upon. | | details | [AuditEvent.EventAuditDetails](#akuity-notifications-webhook-v1-AuditEvent-EventAuditDetails) | The details of the event. | ### AuditEvent.EventAuditActor {#akuity-notifications-webhook-v1-AuditEvent-EventAuditActor} | Field | Type | Description | | ----- | ---- | ----------- | | type | string | The type of actor. | | id | string | The ID of the actor. | | ip | string | The IP address of the actor. | ### AuditEvent.EventAuditDetails {#akuity-notifications-webhook-v1-AuditEvent-EventAuditDetails} | Field | Type | Description | | ----- | ---- | ----------- | | message | string | The message associated with the event. | | patch | string | The patch associated with the event. | | action_type | string | The action type. | ### AuditEvent.EventAuditObject {#akuity-notifications-webhook-v1-AuditEvent-EventAuditObject} | Field | Type | Description | | ----- | ---- | ----------- | | type | string | The type of object. E.g. "team_member", "team", "custom_role", "kargo_instance", etc. | | id | [AuditEvent.EventAuditObject.EventAuditObjId](#akuity-notifications-webhook-v1-AuditEvent-EventAuditObject-EventAuditObjId) | The ID of the object. | | parent_id | [AuditEvent.EventAuditObject.EventAuditParentId](#akuity-notifications-webhook-v1-AuditEvent-EventAuditObject-EventAuditParentId) | The parent ID of the object. | ### AuditEvent.EventAuditObject.EventAuditObjId {#akuity-notifications-webhook-v1-AuditEvent-EventAuditObject-EventAuditObjId} | Field | Type | Description | | ----- | ---- | ----------- | | name | string | The name of the object. | | kind | string | The kind of object. | | group | string | The group of the object. | ### AuditEvent.EventAuditObject.EventAuditParentId {#akuity-notifications-webhook-v1-AuditEvent-EventAuditObject-EventAuditParentId} | Field | Type | Description | | ----- | ---- | ----------- | | name | string | The name of the parent. | | parent_name | string | The name of the parent object's parent (if present). | | application_name | string | The name of the application. | ### PingEvent {#akuity-notifications-webhook-v1-PingEvent} `PingEvent` contains metadata for a ping event. | Field | Type | Description | | ----- | ---- | ----------- | | notification_config_id | string | NotificationConfigID is the organization notification config ID that triggered the ping | ### UsageUpdateEvent {#akuity-notifications-webhook-v1-UsageUpdateEvent} | Field | Type | Description | | ----- | ---- | ----------- | | product | string | The product associated with the usage update. E.g. "ArgoCD", "Kargo", "Akuity Agent". | | usage_type | string | The type of usage. E.g. "applications", "projects". | | usage_threshold | double | The usage threshold. | | max_limit | int64 | The maximum limit. | | usage | int64 | The current usage. | ### WebhookEventPayload {#akuity-notifications-webhook-v1-WebhookEventPayload} `WebhookEventPayload` is the payload sent to the webhook endpoint. | Field | Type | Description | | ----- | ---- | ----------- | | event_time | google.protobuf.Timestamp | The time the event was triggered. | | event_type | WebhookEventType | The type of event. | | organization_id | string | The organization ID. | | event_id | string | The event ID. | | ping_event | [PingEvent](#akuity-notifications-webhook-v1-PingEvent) | Metadata for a ping event. | | usage_event | [UsageUpdateEvent](#akuity-notifications-webhook-v1-UsageUpdateEvent) | Metadata for a usage update event. | | audit_event | [AuditEvent](#akuity-notifications-webhook-v1-AuditEvent) | Metadata for an audit event. | | agent_health_event | [AgentHealthEvent](#akuity-notifications-webhook-v1-AgentHealthEvent) | Metadata for an agent health event. | --- ## Terraform Provider Manage Akuity Platform resources declaratively with the [Akuity Terraform provider](https://registry.terraform.io/providers/akuity/akp/latest). | Resource | Link | | --- | --- | | Documentation, resources & upgrade guides | https://registry.terraform.io/providers/akuity/akp/latest/docs | | Source code | https://github.com/akuity/terraform-provider-akp | | Examples | https://registry.terraform.io/providers/akuity/akp/latest/docs#example-usage | The [registry documentation](https://registry.terraform.io/providers/akuity/akp/latest/docs) covers installation, provider configuration, every resource and data source, and per-version upgrade guides. ## Example ```hcl terraform { required_providers { akp = { source = "akuity/akp" } } } provider "akp" { org_name = "your-organization-name" } ``` Authenticate by setting `AKUITY_API_KEY_ID` and `AKUITY_API_KEY_SECRET` in the environment. The provider targets the US region (`https://akuity.cloud`) by default; EU customers should set `server_url` (or the `AKUITY_SERVER_URL` environment variable) to `https://eu.akuity.cloud`. ## FAQ **Do I need an Akuity API key?** Yes. Create one (see [API Keys](/akuity-portal/organizations/api-keys)) and provide it via the `AKUITY_API_KEY_ID` and `AKUITY_API_KEY_SECRET` environment variables. **Where do I report a bug or request a feature?** Open an issue at https://github.com/akuity/terraform-provider-akp/issues. --- ## Create an Argo CD Instance ## Account Setup :::info For access to the Akuity Platform please [create an Akuity user account](https://hubs.li/Q02l2XGR0). After completing the registration process, activate your account using the link sent to your email. ::: After registering and activating your account, if this is your first time using the platform, you must also create an organization: 1. Click the create or join link. 2. Click + New organization in the upper right hand corner of the dashboard. 3. Name your organization following the rules listed below the Organization Name field. ## Create an Argo CD Instance 1. Navigate to Argo CD. 2. Click + Create in the upper right hand corner of the dashboard. 3. Name your instance following the rules listed below the Instance Name field. 4. (Optionally) Choose the Argo CD version you want to use. 5. Click + Create. It will take several seconds to create your new Argo CD instance (Progressing status next to your new instance's name), so please be patient. Continue on to the [next section](./20-connect-kubernetes-cluster.mdx) to learn about connecting your new Argo CD instance to a running Kubernetes cluster. --- ## Connect a Kubernetes Cluster :::info To move on, you'll need a new or existing Kubernetes cluster to which you can connect your new Argo CD instance. The Akuity Platform's unique, hybrid architecture works with local clusters managed by the likes of [k3d](https://k3d.io) or [kind](https://kind.sigs.k8s.io) just as easily as it works with any other cluster. :::
Create a Kubernetes Cluster Using `kind` (Optional) 1. [Install the `kind` CLI](https://kind.sigs.k8s.io/docs/user/quick-start#installation). 2. Create a cluster using `kind`. ``` kind create cluster --name akuity-connected-cluster ``` You should see the following output: ``` Creating cluster "akuity-connected-cluster" ... ✓ Ensuring node image (kindest/node:v1.25.2) 🖼 ✓ Preparing nodes 📦 📦 📦 📦 ✓ Writing configuration 📜 ✓ Starting control-plane 🕹️ ✓ Installing CNI 🔌 ✓ Installing StorageClass 💾 ✓ Joining worker nodes 🚜 Set kubectl context to "kind-akuity-connected-cluster" You can now use your cluster with: kubectl cluster-info --context kind-akuity-connected-cluster Thanks for using kind! 😊 ``` 3. Check that the cluster works by running `kubectl get nodes`. ``` % kubectl get nodes NAME STATUS ROLES AGE VERSION akuity-connected-cluster-control-plane Ready control-plane 74s v1.25.2 ``` Fetching the nodes will demonstrate that `kubectl` can connect to the cluster and query the API server. The node should be in the "Ready" status.
After your new Argo CD instance is created successfully (Healthy status next to your new instance's name): 1. Navigate to Argo CD → _your instance_ → Clusters. 1. Click + Connect a cluster to add a Kubernetes cluster. 1. Input your Cluster Name. 1. Click Connect Cluster. 1. In the Install Akuity Agent pop-up screen, click Copy to Clipboard :::caution Before pasting the next command, make sure you're connected to the correct cluster. ::: 1. Paste the copied command into your terminal and run it to apply the agent manifest. :::note If you come across any errors while trying to apply the agent manifest, it is recommended to download the agent manifest and apply it manually inside your cluster using the `kubectl apply` command. ::: Once the agent has been successfully installed into your Kubernetes cluster, you should see the cluster listed in the Akuity dashboard with a green heart icon next to the cluster name. This indicates that the cluster is in a healthy state. Now that your Argo CD instance is connected to a Kubernetes cluster, move on to the [next section](./30-enable-admin-user.mdx) to learn about enabling remote access to your instance. --- ## Enable the Argo CD `admin` Account :::note Argo CD instances you create inside the Akuity Platform do not enable the `admin` user by default. ::: To enable the `admin` user on an Argo CD instance: 1. Navigate to Argo CD → _your instance_ → Settings → System Accounts. 1. Enable the Admin Account switch. 1. Click Set password. Then either: * Specify a custom password and click Submit or * Click Regenerate password to generate a strong password. The password will not be displayed. Click Copy to copy the new password to your clipboard. Now that the `admin` user is enabled, move on to the [next section](./40-access-argo-cd-instance.mdx) to learn about accessing your Argo CD instance. --- ## Accessing Argo CD :::info If you have not already enabled the `admin` user for your instance, follow [these instructions](./30-enable-admin-user.mdx). ::: :::info You can find the instance URL for Argo CD by visiting Argo CD → _your instance_. It is found in the upper left hand corner of the screen, to the right of the instance name and health status. ![Argo CD Instance URL](./argo-cd-instance-url.png) ::: ## Access the Argo CD Dashboard 1. Click on the _instance-id_.cd.akuity.cloud. 2. Log in with the username `admin` and the password set (or generated) while [enabling the `admin` user](./30-enable-admin-user.mdx). ## Access Argo CD using the `argocd` CLI 1. Install the `argocd` CLI: **Mac w/Homebrew** ``` brew install argocd ``` **Linux or WSL** ``` curl -sSL -o /usr/local/bin/argocd https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64 chmod +x /usr/local/bin/argocd ``` **Windows w/ Powershell** ``` Invoke-WebRequest -Uri https://github.com/argoproj/argo-cd/releases/latest/download/argocd-windows-amd64.exe -OutFile argocd.exe ``` :::note You will also need to move `argocd.exe` onto your `PATH`. ::: 1. Log in by using the following command and following the prompts: ``` argocd login --grpc-web ``` At this point, you're ready to use your Akuity-managed Argo CD instance as normal. To try it out by deploying an Application in [the next section](./deploy-an-application). --- ## Deploy an Application After [accessing Argo CD](./40-access-argo-cd-instance.mdx), to deploy an `Application`: **UI** 1. In the Argo CD UI, navigate to Applications. 2. Click on NEW APP. 3. Under GENERAL, 1. set Application Name to `helm-guestbook`. 2. set Project Name to `default`. 4. Under SOURCE, 1. set Repository URL to `https://github.com/argoproj/argocd-example-apps`. 2. Set Path to `helm-guestbook`. 5. Under DESTINATION, set Cluster URL to your cluster URL. - The URL will be in the format `https://cluster-:8001`, where `` is the name used [connecting your Kubernetes cluster](./20-connect-kubernetes-cluster.mdx). 6. Set Namespace to `default`. 7. Click on CREATE. The `helm-guestbook` `Application` will be created but will not be synced automatically (because the sync policy was left to the default of `Manual`). 8. Click on the `helm-guestbook` Application card, review the resources to be created in the cluster by clicking on APP DIFF. 9. Then click on SYNC and SYNCHRONIZE. **CLI** 1. Use the `argocd` CLI to create an Application named `helm-guestbook`. ``` argocd app create helm-guestbook \ --repo https://github.com/argoproj/argocd-example-apps.git \ --path helm-guestbook \ --dest-server https://cluster-:8001 \ --dest-namespace default ``` - In `dest-server` URL (`https://cluster-:8001`), replace `` with the name used when [connecting your Kubernetes cluster](./20-connect-kubernetes-cluster.mdx). The `helm-guestbook` `Application` will be created but will not be synced automatically (because the sync policy was left to the default of `Manual`). 2. Check the diff for the Application. ``` argocd app diff helm-guestbook ``` 3. Sync the Application. ``` argocd app sync helm-guestbook ``` Congratulations! You have successfully deployed an application to the Akuity Platform Argo CD Instance. --- ## Getting Started --- ## Sync History ![Sync History Example](./sync-history.jpg) To facilitate the metrics representation of synchronization events, we have introduced a synchronization history feature. It represents the synchronization event counts and duration in time series format. You can also use various filters and group by results. The feature also includes detailed table of individual events. This feature can be viewed from 3 levels. #### 1. Argo CD Application - Covers all the synchronization events happened in the particular Argo CD application. - You will need to install sync history extension in order to see this view. Go to Argo CD → _your instance_ → Settings → Extensions. Click Install in Akuity Sync History extension. - You can then go to the instance's Argo CD UI, Select any Application and click on Application Details. Then panel will have the Sync History tab. ![Sync History Extension](./sync-history-extension.png) #### 2. Argo CD Instance - Covers all the synchronization events happened in all the Application under this Instance. - You can see this in Summary tab of Instance on Akuity Platform. #### 3. Organization :::note **only accessible by an Organization owner and not anyone else.** ::: - Covers all the synchronization events happened in all the Application of All Instance belongs to the organization. - You can see this in Summary tab of your oganization page. ### Filters Events can be filtered by combining various parameters. Available filters are **Instance Name**, **Application Name**, **Project Name**, **Initiator**, **Repository** and **Label**. > Note that not all filters are available in all views. For example, Sync History Extension in Argo CD cannot have filters Instance name and Application name. Quick and custom time range filter is also available. For example, you can select the events in last year or last week. ### Group By and Interval This is specifically useful for graph representation. You can group events by **Status** (Successful/Failed), **Application**, **Instance**, **Project** or **Initiator**. Interval can help adjusting time series graphs frequency. You can select interval by **Hour**, **Day**, **Week**, **Month** or **Year**. ### Reports Filters and Group By can be combined to create shareable reports that will be useful to diagnos issues or anamoly efficiently. You can either copy the URL from browser and share OR Click on the copy icon in right side of filter section. ### Events Table Events table include a list of detailed synchronization events. Filters will be applied to the table as well. Details of individual event includes **Application Name**, **Application Project**, **Application Repository**, **Application Labels**, **Event start and end date**, **Sync Event initiator**, **Event status** and **Message**. --- ## Akuity Platform Dashboard The [Akuity Platform dashboard](https://akuity.cloud) is where you provision, and manage all aspects of your Argo CD instances. --- ## Advanced Settings --- ## General ### Installation Namespace - Use the Installation Namespace field to deploy the agent to a different namespace. The default namespace is `akuity`. :::note Operators can only configure this setting during the initial deployment of the agent. ::: ### State Replication - The State Replication toggle allows disconnecting the cluster from the Akuity Platform without losing core Argo CD features. See [State Replication](./20-state-replication.md) for more information. :::note Operators can only configure this setting during the initial deployment of the agent. ::: ### Redis Tunneling - The Redis Tunneling toggle enables the ability to connect to Redis over a web-socket tunnel that allows using Akuity agent behind HTTPS proxy. ### Private Connectivity - The Private Connectivity setting controls how the agent connects to the Akuity Platform. Public connects over the public internet, while Private connects through an AWS interface endpoint in your VPC using AWS PrivateLink. See [Private Connectivity (AWS PrivateLink)](/akuity-portal/security/private-link) for the full setup guide. :::note Private requires a connected AWS account with an available PrivateLink connection. Integration (direct) clusters are agentless and always use public connectivity. ::: ### Auto Update - Toggle Auto Apply Changes off to prevent the agent from automatically upgrading its components. :::note[Manual Updates to the Akuity Agent] With auto upgrades disabled, users must apply the agent updates manually. To accomplish this, go to the Clusters menu for the Argo CD instance and click Install Agent on the desired cluster, then run the provided command with the `kubectl` context set for the corresponding cluster. ::: ### Namespace Scoped - Toggle Namespace Scoped to limit the agent to only deploying resources into its namespace. :::note Operators can only configure this setting during the initial deployment of the agent. ::: ### Agent Size - In the Agent Size section, choose the size of your Akuity Agent. This selection only impacts the resources allocated to the Akuity Agent within your cluster and does not impact your billing in any way. Optimized Default Agent Sizes |Agent Size | Controller Memory |Controller CPU | Repo Server Memory | Repo Server CPU | Repo Server Replicas | |-----------|-------------------|---------------|--------------------|-----------------|----------------------| |Small |0.5GB |0.25CPU |0.25GB |0.25CPU |2 | |Medium |1GB |0.50CPU |0.50GB |0.25CPU |2 | |Large |2GB |1CPU |0.50GB |0.25CPU |3 | |Auto |Auto |Auto |Auto |Auto |Auto | :::caution Custom Agent Sizes will override manually created [`Agent Kustomizations`](/argocd/managing-instances/clusters/agent-advanced-settings#agent-size-kustomization). All other Kustomizations will remain the same. ::: #### Cluster Autoscaling (Auto) When you set a cluster's size to **Auto**, the Akuity Agent continuously right-sizes the Argo CD application controller and repo server running in that cluster. CPU and memory are adjusted based on actual resource usage. Repo server replica count is adjusted based on the live request queue, using the [`argocd_repo_pending_request_total`](https://argo-cd.readthedocs.io/en/latest/operator-manual/metrics/) metric: if requests are backing up, it adds a replica; if the queue is empty, it removes one. Application controller status and operation processor counts are adjusted based on the number of managed applications. If a pod is OOMKilled, the agent detects it immediately and scales up both memory and CPU resources. CPU and memory scale up when average usage exceeds **80%** of the current allocation, and scale down when it drops below **30%**, preventing flapping. ### Labels & Annotations - Add applicable labels and annotations as key/value pairs in the Labels and Annotations sections of the Advanced settings menu. * Click + Add to add a key/value pair. * Click the trash bin icon next to a key/value pair to delete it. ### Managed Cluster Kubeconfig - Use the Managed Cluster Kubeconfig field to use a different kubeconfig than the default `in-cluster` kubeconfig. This is useful if you want to e.g. connect a [vCluster](https://www.vcluster.com/) from a host cluster. * The agent needs to be installed into a location where there is a secret configured with a `kubeconfig`. * The default Secret Name is `cluster-config`, this is configurable. * If you have the kubeconfig located under a specific key in the secret, that's also configurable (see Secret Key) ### Notifications Settings Source - Use the Notifications Settings Source setting to configure where the notification controller reads its configuration (ConfigMaps and Secrets). Choose from the available options: - **"Control Plane"**: Uses the control plane cluster for notification settings (default behavior) - **"Agent Host"**: Uses the managed cluster for notification settings :::info This feature is only available in Akuity Argo CD (versions with the `-ak` postfix) and is not available in the open-source version of Argo CD. ::: :::note When using this feature, you need to ensure that the required notification configuration exists on the managed cluster: - **ConfigMap**: `argocd-notifications-cm` - Contains notification templates and triggers - **Secrets**: Any secrets needed for notification services (e.g., Slack webhooks, email SMTP credentials, etc.) These resources must be present in the managed cluster's namespace where the notification controller is running. ::: This feature allows the notification controller to read notification settings from the managed cluster while continuing to manage Argo CD applications from the control plane. This is useful when you want to keep notification configuration separate from application management. --- ## Manifests Customization ### Akuity Custom Image Registry - Enter where to pull the agent image from using the Akuity Custom Image Registry field. The default registry is [`quay.io/akuity`](https://quay.io/repository/akuity/agent?tab=tags). ### Argoproj Custom Image Registry - Enter where to pull the Argo CD images from using the Argoproj Custom Image Registry field. The default registry is [`quay.io/argoproj`](https://quay.io/repository/argoproj/argocd?tab=tags). ### Notifications Controller Log Level - Set the logging level of the `argocd-notifications-controller`: `debug|info|warn|error (default "info")`. ### Repo Server Env Variables - Enter an environment variable that you would like to configure for the `argocd-repo-server`. Example: ```yaml ARGOCD_EXEC_TIMEOUT: 'value' ARGOCD_REPO_SERVER_PARALLELISM_LIMIT: 'value' HELM_REGISTRY_CONFIG: 'value' ``` :::info Please contact [`support`](https://support.akuity.io/) on best practices and optimization of the `argocd-repo-server`. ::: ### Custom CA Bundle - Use the Custom CA Bundle field to provide a PEM bundle of one or more CA certificates that the agent workloads should trust in addition to the well-known public CAs. This is typically needed when the agent runs behind a TLS-intercepting proxy (for example, Zscaler) or connects to services that use certificates issued by a private CA. When a bundle is set, every agent workload combines it with the default trust store and mounts the result at `/etc/ssl/certs/ca-certificates.crt`, so all components — including `git` — trust the additional CAs. Updating or clearing the bundle restarts the agent workloads automatically. :::note - A single certificate or a bundle of several certificates is accepted. All certificates must be valid (unexpired) PEM-encoded `CERTIFICATE` blocks. - New clusters inherit the bundle configured in [`Agent Default Settings`](/argocd/managing-instances/settings/advanced/agent-default-settings), unless a bundle is provided when connecting the cluster. - Integration (direct) clusters are agentless and do not support a custom CA bundle. ::: ### Kustomization - The Akuity Platform supports customizing the Akuity Agent manifests using a `Kustomization`. #### Agent Size Kustomization: In some cases the optimized default Agent sizes might not be enough for all use cases. The following example describes how to increase the resource limits/request for both the `argocd-repo-server` & `argocd-application-controller`. ```yaml apiVersion: kustomize.config.k8s.io/v1beta1 kind: Kustomization patches: - patch: |- apiVersion: apps/v1 kind: Deployment metadata: name: argocd-repo-server spec: template: spec: containers: - name: argocd-repo-server resources: limits: memory: 2Gi requests: cpu: 750m memory: 1Gi target: kind: Deployment name: argocd-repo-server ``` ```yaml apiVersion: kustomize.config.k8s.io/v1beta1 kind: Kustomization patches: - patch: |- apiVersion: apps/v1 kind: Deployment metadata: name: argocd-application-controller spec: template: spec: containers: - name: argocd-application-controller resources: limits: memory: 4Gi requests: cpu: 1000m memory: 2Gi target: kind: Deployment name: argocd-application-controller ``` --- ## State Replication The State Replication feature on the Akuity Platform allows you to disconnect a managed cluster from the platform without losing core Argo CD features. This feature is immutable and can only be enabled during cluster creation. Once enabled, all Application and Project CRDs are synced to the managed clusters, and the application controller in the managed cluster is switched to work with the managed cluster instead of the Akuity Platform control plane cluster. ## Enabling State Replication To enable the State Replication feature during cluster connection, follow these steps: 1. Under Advanced settings, locate the flag called State Replication. 1. Toggle the flag to enable State Replication. 1. Complete the cluster connection process. ## Using State Replication Once the State Replication feature is enabled, the application controller in the managed cluster will work with the managed cluster instead of the control plane cluster. This means that even if the connection to the control plane is lost, core ArgoCD functionality will still be working. :::caution Changing the version of the instance won't update CRDs in the managed cluster, because Akuity Agent doesn't have permission to do that, hence the agent manifest needs to be reapplied manually. ::: ### UI Access To access the Argo CD UI in the managed cluster, follow these steps: 1. Log in using the [Argo CD CLI](https://argo-cd.readthedocs.io/en/stable/cli_installation/) in [core](https://argo-cd.readthedocs.io/en/stable/operator-manual/core/) mode. ```bash kubectl config set-context --current --namespace=akuity # change current kube context to the akuity agent namespace argocd login --core ``` 1. Make the UI locally available. ```bash argocd admin dashboard ``` --- ## Credential Rotation The agent in each managed cluster contains several components which require credentials from the Akuity Platform. You can easily rotate credentials for those from the Akuity Platform. You can rotate the credentials for a single managed cluster or multiple at once. - To rotate the credentials of multiple clusters, go to _your instance_ → clusters tab → click security icon above the clusters table. Either select All Clusters or Selected Clusters and click on Rotate. - To rotate the credentials of an individual cluster, go to _your instance_ → clusters tab → click on the three-dot button under Action column → Click on Rotate Credentials → Click on Confirm. This will trigger an update to the cluster(s) in the background. > NOTE: If the cluster has Auto Upgrade disabled, you must re-apply the manifest. --- ## Support Access Support Access allows Akuity support engineers to access the `argocd-application-controller` pod in managed clusters when troubleshooting is required. This feature provides temporary, time-limited access that can be enabled and disabled as needed. ## Enabling Support Access To enable support access for a managed cluster: 1. Navigate to your Argo CD instance → Clusters tab. 2. Find the cluster you want to enable access for. 3. Under the Actions tab, click on the three-dot button. 4. Locate the Manage Support Access section. ![Support Access Section](/img/argocd_clusters_05.jpg) 5. Toggle the Enabled switch to enable access. 6. Set the Duration field to specify how many minutes the access should remain active. 7. Click Save to apply the changes. ![Support Access Modal](/img/argocd_clusters_06.jpg) Once enabled, Akuity support engineers will have access to the `argocd-application-controller` pod in the specified cluster for the configured duration. ## Disabling Support Access Support access can be disabled in the following ways: ### Automatic Expiration Access will be automatically removed after the specified number of minutes elapses. ### Manual Disabling To manually disable support access before the timer expires: 1. Navigate to the cluster details as described above. 2. Toggle the Enabled switch to disable access. 3. Click Ok to apply the changes. ## Security Considerations - Support access is temporary and automatically expires after the specified duration. - Access is limited to the `argocd-application-controller` pod only. - You can monitor and control when support access is active. - Access can be revoked immediately at any time by disabling the feature. --- ## Maintenance Mode Maintenance Mode allows you to temporarily exclude managed clusters from health monitoring and alerting when performing planned maintenance activities. This feature helps prevent false alerts during scheduled maintenance windows while ensuring monitoring is automatically restored after the maintenance period. You maintain full control to disable maintenance mode at any time. The Argo CD applications continue to sync and deploy normally and the cluster remains operational for application workloads. ## Enabling Maintenance Mode To enable maintenance mode for a managed cluster: 1. Navigate to your Argo CD instance → Clusters tab. 2. Find the cluster you want to put into maintenance mode. 3. Under the Actions column, click on the three-dot button. 4. Locate the Enable Maintenance Mode section. ![Maintenance Mode Section](/img/argocd_clusters_07.jpg) 5. Enter the expiration day and time for maintenance mode. This is the date and time when maintenance mode will automatically expire and monitoring will be restored. 6. Click Save to apply the changes. ![Maintenance Mode Modal](/img/argocd_clusters_08.jpg) Once enabled, the cluster will be excluded from health monitoring and alerting. The 🔧 icon indicates that the cluster is in maintenance mode. ![Cluster in Maintenance Mode](/img/argocd_clusters_09.jpg) ## Disabling Maintenance Mode Maintenance mode can be disabled in the following ways: ### Automatic Expiration Maintenance mode will be automatically disabled after the expiration time that you set to ensure monitoring is restored. If maintenance activities require more time, you will need to manually re-enable maintenance mode. ### Manual Disabling To manually disable maintenance mode before the expiration time: 1. Navigate to the cluster actions as described above. 2. Locate the Disable Maintenance Mode section. 3. Click Disable to apply the changes. ![Disable Maintenance Mode Modal](/img/argocd_clusters_10.jpg) --- ## Regenerate Manifests The **Regenerate Manifests** feature allows you to bump the cluster generation, which triggers the agent to re-apply all manifests in the managed cluster. This is useful when you need to force a refresh of the cluster configuration or recover from inconsistent states. You can regenerate manifests for a single managed cluster or multiple at once. - To regenerate manifests for multiple clusters, go to _your instance_ → clusters tab → click refresh icon above the clusters table. Either select All Clusters or Selected Clusters and click on Regenerate. ![Regenerate Manifests Multiple Clusters](/img/argocd_clusters_12.jpg) - To regenerate manifests for an individual cluster, go to _your instance_ → clusters tab → click on the three-dot button under Action column → Click on Regenerate Manifests → Click on Confirm. ![Regenerate Manifests Modal](/img/argocd_clusters_11.jpg) --- ## Akuity Agent The Akuity Agent is a component installed into a managed cluster allowing it to be managed by an Argo CD instance on the Akuity Platform. Every cluster agent which is installed into Kubernetes clusters will have a corresponding cluster entry in Argo CD and will be available as an Argo CD Application destination. ## Requirements To manage a cluster in the Akuity Platform, the cluster agent only needs outbound internet access to the Akuity Platform control plane. It is unnecessary for the Kubernetes API server endpoint to be public. ## Installation To install and connect an agent, you must have already created an Argo CD instance in the Akuity Platform, as well as a kubectl context to a cluster you wish to be managed. 1. Navigate to a single Argo CD instance. 1. From the Clusters tab, click + Connect a cluster. 1. Provide a name for the cluster and click + Connect cluster. 1. Once the cluster entry has been created, installation manifests will be generated specific to the cluster. 1. Copy the installation command and run in a terminal with kubectl context to your cluster. The installation will install the required components into an `akuity` Namespace. Once the Akuity Agent shows as available in the Akuity Platform Portal, it is possible to deploy to the cluster using Argo CD. ### Connecting to an Upbound MCP To connect an Argo CD instance on the Akuity Platform to an Upbound managed control plane (MCP), you must have already [created an Argo CD instance](/argocd/getting-started/create-argo-cd-instance) and configured an [Upbound MCP](https://docs.upbound.io/getstarted/). 1. Create a kubeconfig file for your Upbound MCP using the `up ctx` command . This example saves the kubeconfig to a file named `mcp-kubeconfig.yaml`. ``` up ctx -a -f mcp-kubeconfig.yaml ``` The resulting kubeconfig file will look like: ```yaml apiVersion: v1 clusters: - cluster: server: https://proxy.upbound.io/v1/controlPlanes/.... name: upbound-akuity-dev contexts: - context: cluster: upbound-akuity-dev user: upbound-akuity-dev name: upbound-akuity-dev current-context: upbound-akuity-dev kind: Config preferences: {} users: - name: upbound-akuity-dev user: exec: apiVersion: client.authentication.k8s.io/v1 args: - organization - token command: up env: - name: ORGANIZATION value: - name: UP_PROFILE value: interactiveMode: IfAvailable provideClusterInfo: false ``` Store the `server` and `ORGANIZATION` field values from the kubeconfig as those will be necessary to connect to AKP ArgoCD. 2. Go to Upbound console. Go to the My Account page and create a new `Token` from the `API Tokens` section. ![Upbound Token](/img/argocd_clusters_02.png) 3. Navigate to the required Argo CD instance in Akuity Platform. 4. From the Clusters tab, click + Integration. 5. Provide the name for the cluster. 6. Choose `Upbound` option under `Provider` section inside the modal and put the `Server`, `Token` and `Organization Name` values you recorded previously in the respective input fields. ![AKP Integration](/img/argocd_clusters_03.png) 7. Click + Connect cluster. 8. Once the cluster is connected, you will see a new entry in the cluster table with an upbound logo beside the name. ![AKP Cluster](/img/argocd_clusters_04.png) ## Upgrading Once installed, agents are automatically upgraded upon updates to Argo CD instances (e.g. upgrading Argo CD itself, resizing, applying new labels or annotations). When Argo CD configuration is updated, the agent version will be also be updated to the latest appropriate version compatible with the Argo CD instance. ## Uninstalling To uninstall the Akuity Agent from a managed cluster: 1. In Argo CD, first delete any applications which are currently deploying to the cluster. As a convenience, the Akuity Platform automatically labels all Argo CD Applications with `cluster=` label, allowing you to easily filter applications by destination cluster name. :::tip If you wish to preserve existing resources in the cluster, or the cluster is no longer available, you can perform a [non-cascaded delete](https://argo-cd.readthedocs.io/en/stable/user-guide/app_deletion/). A non-cascaded delete is a non-destructive operation which deletes only the Argo CD application object, and none of the underlying resources in the cluster. ::: 2. Once all applications targeting the cluster have been removed, run the following commands to delete the agent resources: ```shell kubectl delete namespace akuity kubectl delete clusterrole akuity-agent- kubectl delete clusterrole akuity-argocd-application-controller- kubectl delete clusterrolebinding akuity-agent- kubectl delete clusterrolebinding akuity-argocd-application-controller- ``` Alternatively, if you have downloaded the agent installation manifest you could execute: ```shell kubectl delete -f akuity-manifests-.yaml ``` 3. In the Portal UI, navigate to the Clusters tab of the Argo CD instance and click the trash icon next to the cluster to remove the entry. ## FAQ Q: Why do the cluster URLs use HTTP? Clusters in open-source Argo CD use HTTPS. A: In the Akuity Platform, every cluster URL is an alias for `localhost`, and there is **no** unencrypted communication that leaves the local `application-controller` pod on your cluster. You confirm this by checking an `application-controller` pod on your cluster. An easy way to check for this is to grep for the presence of `hostAliases`, like this: ```shell kubectl get pod argocd-application-controller- -o yaml | grep -A 3 hostAliases ``` The output will be ```yaml hostAliases: - hostnames: - cluster- # Where is the name of your cluster. ip: 127.0.0.1 ``` --- ## Control Plane The control plane components include Argo CD API Server, Application Controller (powering app-of-apps pattern), and Application Set Controller. The Akuity Platform control plane components are continiously monitored by Akuity engineers to ensure the platform is running smoothly. Optionally you can expose Prometheus metrics for the control plane components to allow you to monitor the platform yourself. ## Exposing Prometheus Metrics To expose Prometheus metrics for the control plane components: 1. Navigate to the Argo CD → _your instance_ → Settings → External Access section. 2. Scroll down to the Controlplane Metrics section. 3. Toggle the Enable switch. 4. Provide the username and password for the metrics endpoint. 5. Click Save. The metrics endpoint will be available at `-metrics.cdsvcs.akuity.cloud`: * `/argocd-server` - Exposes metrics for the Argo CD API Server. * `/application-controller` - Exposes metrics for the Argo CD Application Controller. * `/application-set-controller` - Exposes metrics for the Argo CD Application Set Controller. --- ## Akuity Datadog Addon Datadog is a powerful monitoring platform that integrates seamlessly with Argo CD components `argocd-repo-server` and `argocd-application-controller`. When using Datadog for your monitoring, ensure [Datadog Agent](https://docs.datadoghq.com/integrations/argocd/) is installed in your cluster. ## Datadog Addons via Akuity Portal If you’re using the Akuity Portal (UI), enabling Datadog is straightforward: 1. Navigate to your cluster settings on [akuity.cloud](https://akuity.cloud/). 2. Click on Add to enable the Datadog option under the Addons section. 3. Update the cluster and apply your changes. ## Datadog Addons via Declarative Specs To configure Datadog integration declaratively using the Cluster custom resource definition (CRD), you can set the `datadogAnnotationsEnabled` flag to `true`. Below is an example configuration for metrics collection of `argocd-repo-server` and `argocd-application-controller` in a dev cluster: ``` apiVersion: argocd.akuity.io/v1alpha1 kind: Cluster metadata: labels: env: dev name: dev namespace: akuity spec: data: datadogAnnotationsEnabled: true appReplication: false autoUpgradeDisabled: false multiClusterK8sDashboardEnabled: true size: large targetVersion: 0.5.58 ``` ## Datadog Addons via Akuity Terraform Provider To integrate using infrastructure-as-code, the Datadog addon can be enabled in your Terraform configuring the `akp_cluster` resource. Below is the example configuration: ``` resource "akp_cluster" "example" { instance_id = data.akp_instance.example.id name = "test-cluster" namespace = "akuity" labels = { test-label = true } annotations = { test-annotation = false } spec = { namespace_scoped = true description = "test-description" data = { size = "small" auto_upgrade_disabled = true target_version = "0.5.58" managed_cluster_config = { secret_key = "secret" secret_name = "secret-name" } datadog_annotations_enabled = true eks_addon_enabled = false } } ``` --- ## Prometheus Operator ## ServiceMonitors The Prometheus Operator supports the use of `ServiceMonitor` resources to scrape metrics from Argo CD components. Deployment of the Prometheus Operator and corresponding `ServiceMonitor` resources to each managed cluster is the responsibility of the cluster administrator and is considered out of scope for this document. Below is an example configuration for scraping metrics from both the `argocd-repo-server` and `argocd-application-controller` for a single managed cluster: :::info The `metadata.namespace` field must match the namespace where the Akuity Agent is deployed (default: `akuity`). The `metadata.labels.release` should align with a label defined in the Prometheus Operator's `serviceMonitorSelector`, particularly when using [kube-prometheus-stack](https://github.com/prometheus-community/helm-charts/blob/main/charts/kube-prometheus-stack/values.yaml). ::: ```yaml apiVersion: monitoring.coreos.com/v1 kind: ServiceMonitor metadata: name: argocd-repo-server-metrics namespace: akuity labels: release: kube-prometheus-stack spec: selector: matchLabels: app.kubernetes.io/name: argocd-repo-server endpoints: - port: metrics interval: 30s --- apiVersion: monitoring.coreos.com/v1 kind: ServiceMonitor metadata: name: argocd-application-controller-metrics namespace: akuity labels: release: kube-prometheus-stack spec: selector: matchLabels: app.kubernetes.io/name: argocd-metrics endpoints: - port: metrics interval: 30s ``` ## Akuity Managed Cluster Dashboard A reference Grafana dashboard can be downloaded below to get started: ![Akuity Dashboard URL](/img/akuity_dashboard.png) Download Akuity Dashboard --- ## Akuity Agent(20-agent) The Argo CD controllers deployed alongside the Agent can be monitored using the standard set of Prometheus metrics available for each component. In most cases, monitoring the `application-controller`, `repo-server`, and `notifications-controller` provides sufficient coverage. While the `akuity-agent` itself does not expose Prometheus metrics, it includes a readinessProbe as part of its deployment. Monitoring the Ready condition of the pods is a reliable way to ensure they are connected and functioning correctly. --- ## Monitoring The Akuity Platform includes a control plane hosted by Akuity and an Akuity Agent deployed in each managed cluster. Each component has its own dedicated monitoring solution. --- ## General Settings ## Change Version The version of a managed Argo CD instance can be upgraded (or downgraded) easily using the Akuity Platform. 1. Navigate to Argo CD → _your instance_ → Settings → General. 1. Under Change Version, select your desired version. 1. Click Save. Once saved, the Akuity Platform will automatically update the instance. After the operation is complete, the instance will show a healthy status in the dashboard, indicating success. :::caution Changing the version of the instance will trigger an update of the Akuity Agent on all connected clusters. The operation is carried out by a temporary job executed in the agent's namespace. Automatic updates to the Akuity Agent can be disabled by default for all clusters on an instance and per cluster. See Disable Auto Upgrade in [Agent Advanced Settings](../20-clusters/10-agent-advanced-settings.mdx). ::: :::note A similar job is used when modifying cluster options such as Agent size, Labels or Annotations, to automatically update the agent configuration in the connected clusters. ::: ## Applications in any namespace The [Applications in any namespace](https://argo-cd.readthedocs.io/en/stable/operator-manual/app-any-namespace/) is an Argo CD feature that allows you to store Application resources in any namespace of a control plane cluster. To enable this feature, navigate to Argo CD → _your instance_ → Settings → General and toggle the App In Any Namespace switch. Once feature is enabled, you can create additional namespaces as well as Application resources in new namespace of a control plane cluster using [declarative management approach](./10-features/30-declarative-management.md). Make sure to allow the additional namespaces in the required Argo CD project as [described](https://argo-cd.readthedocs.io/en/latest/operator-manual/app-any-namespace/#allowing-additional-namespaces-in-an-appproject) in the official documentation. Example: ```yaml apiVersion: argoproj.io/v1alpha1 kind: AppProject metadata: name: test namespace: argocd spec: destinations: - name: '*' namespace: '*' server: '*' sourceNamespaces: - test sourceRepos: - '*' --- apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: my-app namespace: test spec: destination: name: test namespace: default project: test source: path: guestbook repoURL: https://github.com/argoproj/argocd-example-apps.git targetRevision: HEAD ``` To apply this manifest, run `akuity argocd apply --name -f .yaml`. This will create the application resource in the `test` namespace. ## Instance Termination Protection Instance termination protection prevents an Argo CD instance from being accidentally deleted. When enabled, any attempt to delete the instance will be blocked until the protection is explicitly disabled. To enable termination protection: 1. Navigate to Argo CD → _your instance_ → Settings → General. 2. Toggle the Enable Termination Protection switch. 3. Optionally, enter a message in the Instance Protection Notes field. This message is displayed to anyone who attempts to delete the instance, and can be used to explain why the instance is protected or who to contact for more information. 4. Click Save. ![Instance Termination Protection](/img/argo_settings_instance_protection.jpg) --- ## Webhooks Argo CD polls Git repositories every three minutes to detect changes to the manifests. To eliminate this delay from polling, the Argo CD API server can be configured to receive webhook events from any of the following services: * [Bitbucket](https://bitbucket.org/) * [Bitbucket Server](https://www.atlassian.com/software/bitbucket/enterprise) * [GitHub](https://github.com/) * [GitLab](https://about.gitlab.com/) * [Gogs](https://gogs.io/) :::note The webhook handler doesn't differentiate between branch events and tag events where the branch and tag names are the same. ::: A hook event for a push to branch `x` will trigger a refresh for an app pointing to the same repo with targetRevision: `refs/tags/x`. ## Configuring webhooks The webhook should be configured using the appropriate Git provider user interface. For any Git provider, you would need to configure a payload URL, content type, and optional shared secret. The payload URL is your Argo CD instance hostname followed by `/api/webhook` path. For example `https://my-argocd-instance.cd.akuity.cloud/api/webhook`. The content type should be `application/json`. :::note ApplicationSet generator webhooks use the same payload URL. ::: ## Configuring shared secrets Configuring a webhook shared secret is optional since Argo CD treats all webhooks as nothing more than untrusted cues to refresh configuration from a trusted source (a process that already occurs at three-minute intervals). However, if access to your Argo CD instance is not narrowly restricted to [clients with specific IPs or within specific CIDR ranges](./20-security-and-access/40-external-access.md), then configuring a webhook secret is recommended to prevent the possibility of DDoS attacks: 1. Navigate to Argo CD → _your instance_ → Settings → Webhooks. 2. For each Git provider you wish to configure, click the corresponding button and specify a shared secret. 3. Click Save. :::info After a shared secret is added, it will never be displayed again in the dashboard, but can be redefined or removed. ::: --- ## Custom Styles Custom Styles allows you to personalize the appearance of your Argo CD dashboard with custom logos, themes, and colors. All custom style settings can be located by navigating to Argo CD → _your instance_ → Settings → Custom Styles. ## Dashboard Logo You can customize the logo displayed in the sidebar of the Argo CD dashboard. To upload a custom logo: 1. Click Upload. 1. Select your logo image file. 1. Optionally, check Compress logo to reduce the file size. 1. Click Save. :::tip The recommended logo resolution is 40x40 pixels. ::: ## Theme Select a pre-built theme to change the overall color scheme of the dashboard. Available themes: - Default - RedGold - Navy - Slack - Asphalt - Lavender - Terra - Beachball To change the theme: 1. Select a theme from the Theme dropdown. 1. Preview the changes in the preview panel below. 1. Click Save. ## Color Customization For more granular control, you can customize individual color elements: - **Sidebar**: The navigation sidebar background and text colors - **Page wrapper**: The main content area background - **Base primary button**: Primary action button colors - **Base secondary button**: Secondary action button colors - **Primary text and Link**: Text and hyperlink colors The preview panel shows how your changes will look across different views: - **Applications**: The main applications list view - **Application Details**: Individual application detail page - **Drawer**: Side panel drawers ## Edit as CSS For advanced customization, click Edit as CSS to directly edit the CSS styles. This allows full control over the dashboard appearance beyond the pre-built options. --- ## Chat & Banner Chat & Banner settings allow you to add a support chat link and display banner messages in your Argo CD dashboard. All settings can be located by navigating to Argo CD → _your instance_ → Settings → Chat & Banner. ## Chat The Chat feature adds a help link to your Argo CD dashboard, typically used to direct users to a support channel. To configure the chat link: 1. Enter the support **URL** (e.g., your Slack channel or help desk URL). 1. Enter a **Message** to display as the link text (defaults to "Chat now!" if not specified). 1. Click Save. ## Banner The Banner feature displays a message at the top of every page in the Argo CD UI. This is useful for announcements such as maintenance windows or important notices. For more details, see the [Argo CD Banners documentation](https://argo-cd.readthedocs.io/en/stable/operator-manual/custom-styles/#banners). To configure a banner: 1. Enter the **Message** to display. 1. Optionally, enter a **URL** to make the entire banner text a clickable link. 1. Optionally, toggle Permanent to prevent users from dismissing the banner. 1. Click Save. :::note - You can have banner content without a URL, but not the other way around. - You can have either a permanent banner or a closeable banner, but not both. - Permanent banners display only one line of text, so keep the message short. - Every time the banner is updated, users who previously dismissed it will see it again. ::: --- ## Manifest Generation ## Repo Server Delegate The Akuity platform allows you to delegate Git and Helm repository access to one of the connected clusters. This is useful when you don't want to provide all connected clusters access to private Helm or Git repositories. ### Enabling Git Delegate Git Delegate settings are located in Argo CD → _your instance_ → Settings → Manifest Generation. 1. Switch from All Managed Clusters to Single Managed Cluster 1. Select the cluster you want to use as the Repo Server Delegate. 2. Click Save. :::tip If you wish to use ApplicationSets when enabling Repo Server Delegate you will also need to enable [Application Set Delegate](./30-declarative-management.md#applicationset-delegate) to allow your ApplicationSets access private Helm and Git repositories. ::: The Akuity Platform allows you to choose which config management tools are available for your users. ## Kustomize and Helm Helm and Kustomize are two config management tools supported natively by Argo CD. Use the following steps to configure Helm and Kustomize settings: 1. Navigate to Argo CD → _your instance_ → Settings → Manifest Generation. 1. Locate the desired tool section and make the required settings changes 1. Click Save to apply the changes. ## Config Management Plugins [Config management plugins](https://argo-cd.readthedocs.io/en/stable/operator-manual/config-management-plugins/) is a feature of Argo CD that allows connecting any config management tool with a first-class end-user experience. Akuity Platform provides a user interface that allows registering config management plugins. Use the following steps to register a new plugin: 1. Navigate to Argo CD → _your instance_ → Settings → Manifest Generation. 1. Locate the Config Management Plugins section and click Add New Plugin. 1. Provide the plugin name, image, and version. 1. Configure Generate command and other optional settings. 1. Click Save to apply the changes. :::tip When a Config Management Plugin (CMP) is configured on the Akuity Platform, the control plane’s `repo-server` is automatically disabled to prevent arbitrary containers from running in the cluster. As a result, when using the `app-of-apps` pattern, you’ll need to either register all clusters or enable the [Repo Server Delegate](/argocd/managing-instances/settings/features/manifest-generation#repo-server-delegate) feature to ensure applications sync correctly. ::: ### Migration From Config Management Plugins v1 Akuity Platform supports version 2 of the config management plugins (aka [sidecar plugins](https://argo-cd.readthedocs.io/en/stable/operator-manual/config-management-plugins/#sidecar-plugin)). The first version is deprecated and not supported by the Akuity Platform. Use the following steps to migrate from version 1 to version 2: 1. Convert the v1 config management plugin to v2 plugin spec. The example below compares `kasane` plugin v1 and v2 versions: * v1 configuration: ```yaml apiVersion: v1 data: configManagementPlugins: | - name: kasane init: command: [kasane, update] generate: command: [kasane, show] ``` * v2 spec: ```yaml init: command: - kasane - update generate: command: - kasane - show ``` 1. Register the v2 plugin using the converted specification. Provide the plugin name and the Docker image that contains the plugin binary. --- ## Notifications(10-features) Argo CD allows notifications to be configured using [Kubernetes ConfigMaps and Secrets](https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/). The Akuity Platform provides a convenient way to configure notifications through its dashboard. All notification settings can be located by navigating to Argo CD → _your instance_ → Settings → Notifications. :::tip Check out our how to add [GitHub commit status notifications for Argo CD](/tutorials/notifications/) on the Akuity Platform. ::: ## Configure services 1. Select the Configuration tab. 2. Click + Add New: 1. Select the type of service. 2. Enter all required fields (these will vary by service type). 3. Click Add. Repeat these steps if you want to add more services. :::note Configuration tab doesn't currently support all possible services. For now, only Email and Slack are supported. We are continuing to add support for additional services. If you want to add more services, you can use the YAML Editor tab. ::: 3. Click Save to persist the configuration to a `ConfigMap`. :::note The platform automatically injects `.context.argocdUrl` for you. This means that if you have specified a Custom Domain in Argo CD → _your instance_ → Settings → Security & Access → External Access, `.context.argocdUrl` will automatically be updated. You can override its value using the YAML Editor functionality, in which case the Akuity Platform will leave it as you specified. ::: ## Configure triggers and templates Argo CD comes with a [catalog of predefined triggers and templates](https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/catalog/). 1. Select the Configuration tab. 2. Click Import From Catalog. 3. Click Confirm. You can also define your own Triggers or Templates. Each Trigger uses one Template. You need to add a Template first, or you can add it in the Add Trigger modal: 4. Select the Configuration tab. 5. Click Templates. 6. Click + Add Template. 7. Enter a unique Name. 8. Input configuration in the Template field. Refer to the [Argo CD templates documentation](https://argo-cd.readthedocs.io/en/latest/operator-manual/notifications/templates/) for more details. 9. Click Add. Once your Template is visible in the list, go back and add a new Trigger: 10. Click + Add Trigger 11. Fill in all required fields. 12. Select or add a new Template by following the above steps. 13. Click Add. Repeat these steps if you want to add more triggers or templates. 14. Click Save to persist the configuration to a `ConfigMap`. ## Secrets The Akuity Platform allows you to easily manage sensitive information that can be referenced elsewhere in the configuration of your notifications using a `$` sign (e.g. `$slack-token`). To add a new secret: 1. Select the Secrets tab. 2. Then: 1. Click + New Secret. 2. Enter the secret name (without a `$`) in the Key column. 3. Press the Enter key on your keyboard. 4. Enter the secret's value in the Value column. Repeat these steps if you want to add more secrets. 3. Click Save to persist the data in a `Secret`. :::info After a secret is added, it will never be displayed again in the dashboard, but can be redefined or removed. ::: ## Reading settings from a different cluster :::info This feature is only available in Akuity Argo CD (versions with the `-ak` postfix) and is not available in the open-source version of Argo CD. ::: This feature allows the notification controller to read notification settings from the managed cluster while continuing to manage Argo CD applications from the control plane. This is useful when you want to keep notification configuration separate from application management. By default, the controller reads notification settings from the control plane cluster where it manages applications. ### Configuration This feature is configured through the cluster's [Advanced Settings](/argocd/managing-instances/clusters/agent-advanced-settings#notifications-settings-source) in the Akuity Platform UI. :::note When using this feature, you need to ensure that the required notification configuration exists on the managed cluster: - **ConfigMap**: `argocd-notifications-cm` - Contains notification templates and triggers - **Secrets**: Any secrets needed for notification services (e.g., Slack webhooks, email SMTP credentials, etc.) These resources must be present in the managed cluster's namespace where the notification controller is running. ::: ## Control Plane Notifications Setting Control Plane Notifications will allow a notification controller to monitor and trigger notifications for apps beyond its own cluster. This includes: - Apps deployed to the control plane (app of apps) - Integration clusters (e.g., Kargo, Upbound) By default, a notification controller can only watch and notify for apps deployed to its own cluster. This setting extends this capability to include the control plane and integration cluster apps. To configure this setting: 1. Navigate to the Control Plane Notifications section in the Notifications settings tab. 1. Enable the feature. 1. Select the cluster from the dropdown menu. --- ## Declarative management There are two types of settings that can be managed using the declarative approach: * End users/developers specific settings such as `Application`, `ApplicationSet`, and `AppProject` resources. * Platform-specific settings such as IP allow lists, system accounts and availability of additional Argo CD components. ## Developers-specific settings Declarative management allows you to use the Argo CD control plane on the Akuity platform to host `Application`, `ApplicationSet`, and `AppProject` resources. This is used for implementing: * Argo CD's [app of apps pattern](https://youtu.be/2pvGL0zqf9o) to declaratively specify one Argo CD `Application` resource that points to a Git repository consisting only of other `Application` resources. * [`ApplicationSet`](https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/#the-applicationset-resource) resources to manage a set of Argo CD `Application`s. The resources deployed into the control plane must specify the namespace `argocd` and the destination name `in-cluster` (server `https://kubernetes.default.svc`). The child `Application`s (that deploy anything other than an `Application`, `ApplicationSet`, or `AppProject`) must target a connected cluster other than `in-cluster`. ### Example: App of Apps The parent `Application` created via the Argo CD dashboard: ```yaml apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: example-apps namespace: argocd spec: destination: namespace: argocd name: in-cluster project: default source: repoURL: 'https://github.com/argoproj/argocd-example-apps' path: apps targetRevision: HEAD helm: # Set the destination cluster for the child Applications in the Helm chart. values: |- spec: destination: name: my-cluster ``` - The `destination.name` is `in-cluster` and the `destination.namespace` is `argocd`. This will deploy child `Application`s into the Argo CD control plane on the Akuity Platform. The child `Application` created by the parent app: ```yaml apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: helm-guestbook namespace: argocd spec: destination: name: my-cluster namespace: default project: default source: path: helm-guestbook repoURL: 'https://github.com/argoproj/argocd-example-apps' targetRevision: HEAD ``` - The `destination.name` is `my-cluster`, which is an external cluster connected to the Argo CD instance on the Akuity Platform (See ["Connect a Kubernetes cluster"](../../../01-getting-started/20-connect-kubernetes-cluster.mdx)). This is where the resources for the `guestbook` app will be deployed (i.e., the `Deployment` and `Service`). ### Enabling declarative management To enable declarative management: 1. Navigate to Argo CD → _your instance_ → Settings → General. 1. Scroll down to Control Plane Cluster (in-cluster) and toggle the Enabled switch. 1. Click Save. Once the Argo CD instance has finished progressing, the `in-cluster` destination will be available. --- ## Application Set By default, the ApplicationSet Controller will run on the Control Plane which is fine for most use cases. ApplicationSet Delegate (Single Managed Cluster) compliments the [Repo Server Delegate](/argocd/managing-instances/settings/features/manifest-generation#repo-server-delegate) by allowing ApplicationSets that use webhooks, private Helm, or private git repositories to access the credentials needed to perform git operations. ### ApplicationSet Delegate 1. Switch from Control plane to Single Managed Cluster 1. Select the cluster you want to use as the ApplicationSet Delegate. 2. Click Save. ### Policy (Global) A Policy defines how application is synced between the generator and the cluster. Default is 'empty', options: 'sync' (create & update & delete), 'create-only', 'create-update' (no deletion), 'create-delete' (no update) ### Allow Override Starting with Argo CD v2.8 a policy can be specified per [ApplicationSet](https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Controlling-Resource-Modification/#managed-applications-modification-policies). Enabling the override will allow a policy per ApplicationSet to override a global policy. ### Progressive Syncs :::note Alpha This feature is currently in Alpha status. ::: The Progressive Syncs feature allows you to control the order in which the ApplicationSet controller will create or update the Applications owned by an ApplicationSet resource. This is useful when you need to roll out changes to applications in a controlled, sequential manner rather than all at once. For more details on Progressive Syncs, see the [Argo CD Progressive Syncs documentation](https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Progressive-Syncs/). To enable Progressive Syncs: 1. Navigate to Argo CD → _your instance_ → Settings → Application Set. 1. Scroll down to Progressive Syncs and toggle the Enabled switch. 1. Click Save. ### Using secrets in ApplicationSets For security reasons, the Akuity platform enforces that all secret references in ApplicationSets point to the platform-managed secret named `application-set-secret`. This ensures that the credentials used by your ApplicationSets are securely managed and audited by the platform. :::note Apart from the `application-set-secret` the ApplicationSets can also point to argocd repo credentials. ::: Setting Up Secrets To configure secrets for use with ApplicationSets: 1. Navigate to Argo CD → _your instance_ → Settings → Application Set. 1. Scroll down to Secrets and add your key-value pairs (e.g., tokens, credentials) that you want to store in the application-set-secret. 1. Save the configuration. The platform will automatically create or update the application-set-secret. ### Plugins Generator The ApplicationSet Plugin Generator allows you to configure custom plugin generators that can be used with ApplicationSets. This feature enables you to extend the functionality of ApplicationSet generators by providing your own custom logic for generating application parameters. For detailed information about implementing plugin generators, see the [Argo CD Plugin Generator documentation](https://argo-cd.readthedocs.io/en/latest/operator-manual/applicationset/Generators-Plugin/). #### Adding a Plugin 1. Navigate to Argo CD → _your instance_ → Settings → Application Set. 1. Scroll down to the Plugins Generator section. 1. Configure the following fields: * **Name**: A unique identifier for your plugin (the field is pre-filled with `plugin-`, so you would enter something like `my-custom-plugin` to create `plugin-my-custom-plugin`) * **Base URL**: The base URL of the Kubernetes service exposing your plugin in the cluster (e.g., `http://myplugin.plugin-ns.svc.cluster.local`). In most cases, this will be a deployment running on your cluster and not publicly accessible. * **Request Timeout**: Timeout for requests to the plugin in seconds * **Token**: A token used to authenticate HTTP requests to your plugin 1. Click + Add Plugin to add the plugin configuration. 1. Click Save to apply the changes. :::tip The token should be a strong, randomly generated string that will be used to authenticate requests between the ApplicationSet controller and your plugin. ::: :::note The base URL should point to a Kubernetes service that exposes your plugin. The service should be accessible from the ApplicationSet controller's namespace. **Important**: If your plugin service is not publicly accessible, you will need to enable the [ApplicationSet Delegate](#applicationset-delegate) feature and delegate to the cluster where your plugin service is running. ::: --- ## Image Updater The Akuity Platform can easily enable and configure the [Argo CD Image Updater](https://argocd-image-updater.readthedocs.io/en/stable/). The Image Updater settings are located in Argo CD → _your instance_ → Settings → Image Updater. To enable the Image Updater, go to its setting tab mentioned above, toggle Enable and click on Save. If Image Updater is Enabled, you will get an option below to select a cluster in which you want to run the Image Updater. You can select All Managed Clusters or Single Managed Cluster of your choice. Once the Image Updater is configured on the Akuity Platform, all the operational configurations can be done in the Argo CD instance itself, such as the [`git` write-back method](https://argocd-image-updater.readthedocs.io/en/stable/basics/update-methods/#git-write-back-method) or [update strategies](https://argocd-image-updater.readthedocs.io/en/stable/basics/update-strategies/#semver-update-to-semantic-versions). ## Logs The Argo CD Image Updater runs in your connected cluster, so the logs can be viewed using below command on the cluster. ```shell # namespace is 'akuity' unless you configure different in cluster settings. kubectl logs deployment.apps/argocd-image-updater -n ` ``` In the settings, you can configure the log level from the Log Level dropdown. ## Git ### Git Access for Write-Back Method Before you choose `git` as a write back method, you would need to give an access of the relevant git repository to let Image Updater commit changes. ### Git Commit Options Configure the `git` commit username, email, and message used by the Image Updater. This configuration is optional. 1. Fill the User field. 1. Fill the Email field. 1. Fill the Commit Message Template input. The template is a [Go `text/template` string](https://pkg.go.dev/text/template). Therefore, metadata can be accessed using variables. two common top-level variables are: 1. `AppName` - the name of the Application. 1. `AppChanges` - the list of the changes, which contains: 1. `Image` - the image name. 1. `OldTag` - the previous tag or SHA digest before the update. 1. `NewTag` - the update's new tag or SHA digest. 1. Click Save. ## Container Registries To configure custom private [container registries](https://argocd-image-updater.readthedocs.io/en/stable/configuration/registries/#configuration-of-container-registries): 1. Click the Add Container Registry button. 1. Fill the relevant fields Prefix, Name, API URL, Default Namespace, Credentials, Credential Expire Time and Rate Limit. Hover over the help icon to see more information about a field. 1. Move to the Secrets tab to define private container registry credentials and use it from the dropdown of the Credentials field mentioned in the above step. 1. Click Save. ## SSH Client Configuration The Image Updater supports setting the SSH Client Configuration (i.e., modifying the `~/.ssh/config`). This is used in edge cases when, for example, you need to use the deprecated `ssh-rsa` algorithm. See further explanation in this [pull request](https://github.com/argoproj-labs/argocd-image-updater/pull/373) on the upstream project. ```yaml Host * PubkeyAcceptedAlgorithms +ssh-rsa HostkeyAlgorithms +ssh-rsa ``` --- ## Secrets The Akuity Platform provides a way to manage and synchronize secrets between the control plane and your Kubernetes clusters. This capability is built in to the platform and requires no additional configuration to enable in your clusters. :::caution The Akuity Platform's secret syncing feature is designed for **convenience** and is not as a comprehensive secret management solution. It's best suited for syncing a small number of secrets for Argo CD use cases, such as repository credentials or notification secrets. **For proper secrets management, consider using a dedicated solution like [External Secrets Operator (ESO)](https://external-secrets.io/) or [OpenBao](https://www.openbao.org/).** ::: ## Overview Secrets management has two main components: 1. Syncing secrets from your managed clusters to be used by the Argo CD control plane hosted on the Akuity Platform. 2. Syncing secrets from the Argo CD control plane to your managed clusters. Additionally, the settings tab can now create what are called "managed secrets." This is a shortcut for creating Argo CD secrets without needing to access the Argo CD dashboard directly (though they can still be managed there as well). These features can be used separately or together, depending on your needs. ## Syncing Secrets to the Argo CD Control Plane ### Selecting which Secrets to Sync For security, secrets will not synced unless explicitly allowed by a control plane administrator. This can be done in the "Secrets" settings of the instance as shown below: Allowed secrets are configured by creating a Secret Source. A Secret Source has two fields, one of which must always be set: 1. **Cluster Selector**: A label selector for a clusters you wish to sync secrets from. The [labels for the cluster](../../20-clusters/10-agent-advanced-settings.mdx#labels--annotations) are specified when connecting a cluster to the Akuity Platform. If this field is left empty, then the Label Selector will match secrets from all clusters. 2. **Label Selector**: A [set-based label selector](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#set-based-requirement) for the secrets you wish to sync. If this field is left empty, then the Label Selector will match all secrets for all matching clusters :::tip You can use both Cluster and Label selectors to select specific secrets from specific clusters for more fine grained control ::: ### Creating Secrets :::warning If you create a secret syncing selector _after_ creating a secret in Kubernetes, the secret will not sync until Kubernetes resyncs or you reapply the secret. This is due to the limitation of the Kubernetes API, which only informs when a secret is updated/created. ::: To sync secrets from your managed clusters to the Argo CD control plane, you need to create a secret in your managed cluster with the appropriate labels. The Akuity agent will automatically detect these secrets and sync them to the Argo CD control plane. Secrets must be created in the Agent namespace within a managed cluster (`akuity` by default) and must have the label `akuity.io/secret-sync: "true"` to opt-in to syncing. **Argo CD Secrets (repo-creds, repository)** For Argo CD repository credentials, add the standard `argocd.argoproj.io/secret-type` label. The `argocd.argoproj.io/secret-type` label is what enables Argo CD treat the secret as repository credentials or other Argo CD secret types. To sync the secret from a managed cluster to the control plane, you must also opt-in with the sync label (`akuity.io/secret-sync: "true"`). You can create [secrets declaratively](https://argo-cd.readthedocs.io/en/stable/operator-manual/argocd-repo-creds-yaml/) following Argo CD's format. Here is an example secret that can be used to sync a Git repository credential: ```yaml apiVersion: v1 kind: Secret metadata: name: argoproj-https-creds namespace: akuity labels: argocd.argoproj.io/secret-type: repo-creds # This label is required to enable syncing of this secret akuity.io/secret-sync: "true" # This label could be used to select this secret for syncing team: my-team stringData: url: https://github.com/argoproj type: helm password: my-password username: my-username ``` **Arbitrary Secrets** You can sync any secret to the control plane by adding the `akuity.io/secret-sync: "true"` label. This is useful for syncing secrets that don't fit the Argo CD secret types, such as external secrets managed by other tools, or custom credentials used by ApplicationSet generators or notification triggers. Here is an example of an arbitrary secret that can be synced to the control plane: ```yaml apiVersion: v1 kind: Secret metadata: name: my-custom-credentials namespace: akuity labels: # This label is required to enable syncing of this secret akuity.io/secret-sync: "true" # This label could be used to select this secret for syncing team: my-team stringData: api-key: my-api-key endpoint: https://api.example.com ``` Synced secrets will be available in the Argo CD control plane and can be used in your applications. Once the secret is synced, you will see it appear in the managed secrets list in the "Secrets" settings of the instance: ![Managed Secrets view](/img/secrets_0.png) ### Blocked Secrets For security, certain secrets are never allowed to be synced/mutated by managed clusters. Secrets that meet any of the following criteria are denied: * Secrets with the following names: * `argocd-secret` * `argocd-initial-admin-secret` * Secrets of the following [types](https://kubernetes.io/docs/concepts/configuration/secret/#secret-types): * `kubernetes.io/service-account-token` * Secrets with the following labels: * `argocd.argoproj.io/secret-type=cluster` Attempting to sync/mutate denied secrets will be rejected by the Akuity Platform. ### Adoptable Secrets Certain system secrets can be "adopted" by a managed cluster when synced. These secrets are pre-existing in the control plane, but when a managed cluster syncs its own version, the cluster takes ownership and the control plane defers to the cluster's values. | Secret Name | Purpose | | ----------- | ------- | | `argocd-notifications-secret` | Notification service credentials (Slack tokens, email passwords, etc.) | | `argocd-image-updater-secret` | Image registry credentials for the Argo CD Image Updater | | `application-set-secret` | Credentials used by ApplicationSets (configured via the Application Set settings page) | When a managed cluster adopts one of these secrets, the Akuity Platform UI will display a warning banner indicating which cluster owns the secret, and the edit controls will be disabled to prevent conflicting changes. **To modify an adopted secret**, update it directly on the managed cluster that owns it. **To return control to the Akuity Platform**, remove the `akuity.io/secret-sync: "true"` label from the secret on the managed cluster, or delete the secret entirely from the managed cluster. Once ownership is released, the warning banner will disappear and you'll be able to edit the secret again from the Akuity Platform dashboard. ## Creating and updating managed secrets Managed secrets can be created and updated directly from the "Secrets" settings of the instance. Essentially, this is a convenience wrapper around creating a Kubernetes secret with some extra goodies to make syncing work, so it should look familiar. **Create** To create a managed secret, follow the steps below: You can use a match expression to match labels on the clusters you wish to sync this secret to or you can allow it to sync to all clusters **Update** To update an existing managed secret, click on the edit icon of the secret in the list you wish to edit and then edit any fields desired **Delete** To delete an existing managed secret, click on the delete icon of the secret in the list you wish to delete and then confirm the deletion. ## Syncing Secrets to Managed Clusters Secrets that are synced to the Argo CD control plane or created as managed secrets can also be synced back down to your managed clusters. This enables workflows where a cluster acts "seed" cluster that syncs to all of your other managed clusters. ### Authorizing secrets to be synced Each secret must be explicitly authorized to be synced to a cluster. This can be done on secret creation or by editing an existing secret: All Clusters will sync the secret to all other clusters. Selected Clusters allows you to use a label selector to select which clusters the secret should be synced to. This should match the [labels specified when connecting a cluster](../../20-clusters/10-agent-advanced-settings.mdx#labels--annotations). ### Advanced: Syncing from one cluster to other clusters If you are managing secrets from one of your managed clusters, you "own" that secret and Akuity will not modify any of those secret values. In order to allow the secret to sync to other clusters, you'll need to add one or more of the annotations described below: | Annotation | Description | Example Value | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | | `akuity.io/managed-secret-allowed-cluster-selector` | A set-based label selector that determines which clusters the secret is allowed to be synced to. | `my-label in (cluster2)` | | `akuity.io/managed-secret-allowed-clusters` | A comma-separated list of cluster names that the secret is allowed to be synced to. The reserved string `ALL` can be used to allow syncing to all clusters. | `cluster2,cluster3` | As an example, this is what the same Argo CD repo credentials secret would look like when created in a managed cluster and synced to a specific set of other clusters: ```yaml apiVersion: v1 kind: Secret metadata: name: argoproj-https-creds namespace: akuity labels: argocd.argoproj.io/secret-type: repo-creds # This label is required to enable syncing of this secret akuity.io/secret-sync: "true" # This label could be used to select this secret for syncing team: my-team annotations: # Assumes you have a cluster with the label my-label=cluster2 akuity.io/managed-secret-allowed-cluster-selector: my-label in (cluster2) stringData: url: https://github.com/argoproj type: helm password: my-password username: my-username ``` --- ## RBAC Role-Based Access Control (RBAC) allows you to define fine-grained access policies for your Argo CD instance. All RBAC settings can be located by navigating to Argo CD → _your instance_ → Settings → RBAC. For detailed information about RBAC concepts and policy syntax, see the [Argo CD RBAC documentation](https://argo-cd.readthedocs.io/en/stable/operator-manual/rbac/). ## Default Role The Default Role setting specifies the role that all authenticated users receive by default. This role determines the minimum level of access for anyone who logs into your Argo CD instance. Argo CD provides two built-in roles: - `role:readonly` - Read-only access to all resources - `role:admin` - Unrestricted access to all resources ## OIDC Scopes OIDC Scopes control which OIDC scopes to examine during RBAC enforcement (in addition to the `sub` scope). By default, the `groups` scope is used. This setting is useful when you want to use additional claims from your identity provider for RBAC decisions, such as `email` or custom scopes. To add additional scopes: 1. Click + Add Scope. 1. Enter the scope name. 1. Click Save. ## Logs Access RBAC When enabled, Logs Access RBAC allows you to manage who can view application pod logs in the Argo CD UI independently from general application access. This provides more granular control over sensitive log data. To enable Logs Access RBAC: 1. Toggle the Enabled switch to ON. 1. Click Save. Once enabled, you can use the `logs` resource in your RBAC policies to control access. For example: ``` p, role:developer, logs, get, default/*, allow ``` This policy allows users with the `developer` role to view logs for all applications in the `default` project. ## Policy The Policy section allows you to define RBAC policies that control access to Argo CD resources. To add or modify policies: 1. Edit the policy in the Definition text area. 1. Click Save. You can create multiple policy tabs by clicking the + button next to the Main tab to organize your policies. --- ## System Accounts All system account settings can be located by navigating to Argo CD → _your instance_ → Settings → System Accounts. ## Anonymous user Toggling the Anonymous User switch to ON permits anonymous access to the Argo CD UI. :::info Anonymous users receive the default permissions specified under Argo CD → _your instance_ → Settings → RBAC → Default Role. For read-only access, you should set this default policy to `role:readonly`. ::: ## Admin account Toggling the Admin Account switch to ON creates a system account with the username `admin`. To specify a password for the `admin` user: 1. Click Set Password. Then either: * Specify a custom password and click Submit or * Click Regenerate password to generate a strong password. The password will not be displayed. Click Copy to copy the new password to your clipboard. :::note The Argo CD Admin Account feature is different from the Akuity Platform Admin user role. Please refer to Argo CD documentation for more information about the Admin Account feature, or refer to the Organizations page in the Akuity Platform documentation for more information about the Akuity Platform Admin user role. ::: ## Account management In addition to the `admin` user, the Akuity Platform allows you to create additional system accounts with configurable capabilities: 1. Click Add Account. 1. Type a username in the blank Name field. 1. Select appropriate permissions in the Capabilities field. 1. Click Add. Repeat these steps to add additional system accounts. To set a password for any system user: 1. Click the corresponding Set password button. Then either: * Specify a custom password and click Submit or * Click Regenerate password to generate a strong password. The password will not be displayed. Click Copy to copy the new password to your clipboard. ## Account capabilities * login: Permits the user to log in using the Argo CD UI. * apiKey: Permits the user to generate authentication tokens for API access. This is useful for CI/CD pipelines or other automated processes that need to interact with the Argo CD API. --- ## External Access All external access settings can be located by navigating to Argo CD → _your instance_ → Settings → External Access. ## Custom Domain ### Akuity Subdomain By default, each Argo CD instance's UI will be accessible at `.cd.akuity.cloud`, however, the Akuity Platform does permit you to set a custom domain prefix for each Argo CD Instance. To customize this: 1. Change the value of the Custom Domain field. 1. Click Save. ### Fully Qualified Domain Name If you have a custom domain that you would like to use, you can set up a CNAME record to point to the Akuity Platform's domain. To do this: 1. Create a CNAME record in your DNS provider that points to `.cd.akuity.cloud`. 1. Change the value of the Domain field to your custom domain. 1. Click Save. ## IP Allow List By default, each Argo CD instance is accessible by clients with any IP address, however, this can be narrowed to a specific list of IP addresses or CIDR ranges. To customize this: 1. Under IP Allow List, click + Add New and complete the IP Address and Description (optional) fields. * Repeat this step as necessary. 1. Click Save. To restore access from any IP address, simply remove all entries from the list. :::note Coming Soon We will soon allow you to populate the IP Allow List with known IPs from CI providers such as GitHub Actions. This will allow you to restrict access to the Argo CD UI to the IPs of your providers without the need to create dozens or hundreds of entries manually. ::: ## Private Connectivity Organizations with AWS PrivateLink enabled can take the Argo CD instance off the public internet entirely by switching Private Connectivity to Private. This requires a connected AWS account and is mutually exclusive with the Fully Qualified Domain Name setting. See [Private Connectivity (AWS PrivateLink)](/akuity-portal/security/private-link) for the full setup guide. --- ## Argo CD SSO Configuration The Akuity Platform allows you to configure a single SSO provider for Argo CD, such as GitHub, SAML, or any other supported providers, ensuring secure user access to your Argo CD instance. This guide provides a step-by-step approach to setting up Single Sign-On (SSO) for Argo CD using the Akuity Platform. :::info Argo CD SSO is available in all Professional and Enterprise plans. If you would like to have an SSO configured specifically for your Organization, it is recommended to use the [Akuity Platform SSO](../../../../02-akuity-portal/02-organizations/50-sso.mdx). ::: ## Configuring SSO 1. In your Argo CD Instance, go to Settings. 2. In the left panel, search for Security & Access and go to SSO Configuration. ![SSO Settings](/img/argocd-sso-1.png) 3. Click on Add new connector and select your desired `Type`. ![Connector Type](/img/argocd-sso-02.png) :::note If you don't see your desired connector type in the configuration, it is recommended to use the YAML Editor for advanced configurations. ::: **SAML** 4. Register a New SAML Application: - In your SAML Identity Provider (IdP) portal (e.g., Okta, Microsoft Entra ID, or Auth0), create a new SAML application. - Provide a name (e.g., "Argo CD") and configure the Single Sign-On URL (or ACS URL) to point to the `/api/dex/callback` endpoint of your Argo CD URL (e.g., https://argocd.example.com/api/dex/callback). - After creating the application, download the SAML metadata file from your IdP. This metadata file will contain necessary information like the `Entity ID`, `SSO URL`, and the `public certificate` needed for SAML authentication. 5. Store your *SSO URL* and *Public Certificate* in a secure location since you'll need both in the next steps. 6. Paste your *SSO URL* and *Publc Certificate* (not Base64 encoded) in the connector along with the *username attribute* and *email attribute*, and click Add 7. Finally, click Save in the top-right corner. ![saml sso](/img/saml.png) **Google** 4. Set Up the [OAuth Consent Screen](https://console.cloud.google.com/apis/credentials/consent): - Go to the [OAuth Consent Screen](https://console.cloud.google.com/apis/credentials/consent) in the Google Cloud Console. If you haven't configured it yet, select *Internal* or *External* and click *Create*. - Provide a name for your login app, a user support email, and add *Authorized domains* (e.g., example.com to allow all users with *@example.com* to log in). - Optionally, add an app logo and other information for a customized login experience. - Save and proceed to the *Scopes* section to add `.../auth/userinfo.profile` and `openid` scopes. Review and finalize your setup. 5. Store your *Client ID* and *Client Secret* in a secure location since you'll need both in the next steps. 6. Paste your *Client ID* and *Client Secret* in the connector and click on Add 7. Finally, click on Save in the top right corner. ![alt text](/img/google-sso-argocd.png) **GitHub** 4. In GitHub, register a new application. Go to Settings > Developer Settings and create a new GitHub App. The callback address for the GitHub App should be the `/api/dex/callback` endpoint of your Argo CD URL (eg. https://argocd.eg.com/api/dex/callback) 5. Store your *Client ID* and *Client Secret* in a secure location since you'll need both in the next steps. 6. Paste your *Client ID* and *Client Secret* in the connector and click on Add 7. Finally, click on Save in the top right corner. ![sso github](/img/sso-github.png) :::note Once your connectors have been added and saved, you can also use the YAML Editor to perform advanced configurations. ![YAML Editor](/img/argocd-sso-yaml-editor.png) ::: 8. In order to validate, open a new browser and enter your ArgoCD Instance URL: `https://`. ![argocd-validate-sso](/img/argocd-validate-sso.png) 9. Click on SSO LOGIN and log in to your Argo CD instance. Congratulations! You've successfully set up the Argo CD SSO configuration using Akuity Platform. --- ## Akuity Agent Default Settings The Akuity Agent is a component installed into a managed cluster allowing it to be managed by an Argo CD instance on the Akuity Platform. Every cluster agent which is installed into Kubernetes clusters will have a corresponding cluster entry in Argo CD and will be available as an Argo CD Application destination. ## Default Settings To apply the settings globally go to Argo CD → _your instance_ → Settings → Agent Default Settings. :::note Modifications made here will be applied globally. Additional clusters added to your instance will inherit these settings by default, unless specified via [`Akuity Platform Declarative management`](/akuity-portal/automation/declarative-management). ::: ## Applying Changes When the Agent Default Settings are updated and Save is clicked, the changes will apply only to newly added clusters. To update both existing and future clusters, select Save and Update All Clusters. |Setting | Enabled by Default | |--------------------------------------------------------------------------------------------------------------|--------------------| |[`Auto Apply Changes`](/argocd/managing-instances/clusters/agent-advanced-settings#auto-update) | Yes | |[`State Replication`](/argocd/managing-instances/clusters/agent-advanced-settings#state-replication) | No | |[`Redis Tunneling`](/argocd/managing-instances/clusters/agent-advanced-settings#redis-tunneling) | No | |[`Private Connectivity`](/argocd/managing-instances/clusters/agent-advanced-settings#private-connectivity) | No (Public) | |[`Akuity Customer Image Registry`](/argocd/managing-instances/clusters/agent-advanced-settings#akuity-custom-image-registry) | No | |[`Argoproj Customer Image Registry`](/argocd/managing-instances/clusters/agent-advanced-settings#argoproj-custom-image-registry) | No | |[`Kustomization`](/argocd/managing-instances/clusters/agent-advanced-settings#kustomization) | No | |[`Custom CA Bundle`](/argocd/managing-instances/clusters/agent-advanced-settings#custom-ca-bundle) | No | --- ## Akuity Agent Resource Customization Resource Customization feature allows you to configure how ArgoCD interacts with, monitors, and manages your Kubernetes resources to suit your specific needs. Providing the Group/Kind of the resource, you can customize the following: 1. [Resource Health](https://argo-cd.readthedocs.io/en/stable/operator-manual/health/) 2. [Resource Actions](https://argo-cd.readthedocs.io/en/stable/operator-manual/resource_actions/) 3. [Ignore Differences/Ignore Resource Updates](https://argo-cd.readthedocs.io/en/stable/user-guide/diffing/) 4. [Kubernetes Known Type Fields](https://argo-cd.readthedocs.io/en/stable/user-guide/diffing/#known-kubernetes-types-in-crds-resource-limits-volume-mounts-etc) Refer to the corresponding OSS documentation for more information on these features. ## Enable Resource Customization To enable Resource Customization, follow these steps: 1. Go to Argo CD → _your instance_ → Settings → Resource Customizations. 2. Click on Add Customization to open modal, where you can configure your customization. ![agent-resource-customization-add](/img/argo_settings_resource_customization_add_new.png) 3. Fill in the applicable fields for the customization: - **Group/Kind**: The API group and kind of the resource you want to customize. - **Health Check** (optional): The health check configuration for the resource. - **Actions** (optional): The resource actions configuration for the resource. - **Ignore Differences** (optional): The ignore differences configuration for the resource. - **Ignore Resource Updates** (optional): The ignore resource updates configuration for the resource. This configuration can be disabled so that it doesn't effect anything by a switch "Enable Ignore Resource Updates" below the customizations table. - **Known Type Fields** (optional): The known Kubernetes types configuration for the resource. ![agent-resource-customization-modal](/img/argo_settings_resource_customization_modal.png) 4. Click Add to confirm your configuration. 5. Click Save to save your resource customization settings. ## Modifying Resource Customization You can edit and delete your resource customizations by using table action buttons and saving settings. ![agent-resource-customization-editing](/img/argo_settings_resource_customization_editing.png) ## Cron Job ![cron-job](/img/argo_settings_resource_customization_cron.jpg) If you would like to create a job from a CronJob, in the ArgoCD UI, you can enable this feature in the Resource Customizations settings. :::danger Enabling/Disabling this feature will require manually re-applying the cluster manifests for all connected clusters once confirmed. ::: Follow these steps to enable job creation from CronJobs: 1. Go to Argo CD → _your instance_ → Settings → Resource Customizations. 2. Toggle the `Enable Job creation from CronJobs` toggle. ![crob-job-enable](/img/argo_settings_resource_customization_cron_switch.png) 3. Confirm toggling the setting in the confirmation modal. This setting allows you to create a job from the CronJobs in the ArgoCD UI. It adds the following rules to the akuity-agent ClusterRole in your cluster: ```yaml - apiGroups: - batch resources: - jobs verbs: - create ``` --- ## Reconciliation Settings Reconciliation settings allow you to tune how Argo CD processes application reconciliation. These settings can help prevent resource exhaustion and improve performance in large-scale deployments. All reconciliation settings can be located by navigating to Argo CD → _your instance_ → Settings → Reconciliation Settings. For more details on high availability and rate limiting, see the [Argo CD High Availability documentation](https://argo-cd.readthedocs.io/en/stable/operator-manual/high_availability/). ## Bucket Rate Limiting Bucket rate limiting uses a simple bucket-based approach to prevent resource spikes when many applications need reconciliation simultaneously. To enable bucket rate limiting: 1. Toggle the Enabled switch to ON. 1. Configure the following settings: - **Bucket Size**: The number of items that can be queued in a single burst (default: 500) - **Bucket QPS**: The number of items that can be queued per second (default: 50) 1. Click Save. ## Item Rate Limiting Item rate limiting manages how frequently individual applications can be requeued using exponential backoff. This helps prevent sync loops and controller resource exhaustion. To enable item rate limiting: 1. Toggle the Enabled switch to ON. 1. Configure the following settings: - **Failure Cooldown**: The reset period in milliseconds. Backoff resets if this duration elapses without requeuing (default: 10000ms) - **Backoff Factor**: The multiplier for exponential backoff increases (default: 1.5) - **Base Delay**: The initial backoff value in milliseconds (default: 1ms) - **Max Delay**: The maximum backoff ceiling in milliseconds (default: 1000ms) 1. Click Save. ## Resources The Resources section allows you to control which Kubernetes resources Argo CD monitors and reconciles. ### Inclusions By default, all resource groups/kinds are included. The Inclusions setting allows you to customize the list of included groups/kinds. If specified, only these resources will be monitored. ### Exclusions Configuration to completely ignore entire classes of resource groups/kinds (optional). Excluding high-volume resources improves performance and memory usage, and reduces load and bandwidth to the Kubernetes API server. These are globs, so a `*` will match all values. If you omit groups/kinds/clusters, they will match all groups/kinds/clusters. :::note `events.k8s.io` and `metrics.k8s.io` are excluded by default. ::: Example exclusion configuration: ```yaml - apiGroups: - '*.crossplane.io' kinds: - ProviderConfigUsage ``` ## Compare Options The Compare Options section allows you to configure how Argo CD compares resources during reconciliation. This is specified in YAML format. Available options include: - **ignoreAggregatedRoles**: If set to `true`, differences caused by aggregated roles in RBAC resources are ignored - **ignoreResourceStatusField**: Disables status field diffing in specified resource types. Options: - `crd` - CustomResourceDefinitions (default) - `all` - All resources - `none` - Disabled Example configuration: ```yaml ignoreAggregatedRoles: true ignoreResourceStatusField: crd ``` --- ## Deep Links Deep links enable quick navigation from the Argo CD UI to external systems like Splunk, Datadog, or other monitoring and logging tools. All deep link settings can be located by navigating to Argo CD → _your instance_ → Settings → Deep Links. For detailed information about deep link configuration and URL templates, see the [Argo CD Deep Links documentation](https://argo-cd.readthedocs.io/en/stable/operator-manual/deep_links/). ## Link Types Argo CD supports three types of deep links, each appearing in different locations within the UI: ### Application Links Application links appear in the application summary tab. These links have access to `application` and `cluster` data in their URL templates. ### Project Links Project links appear in the project tab. These links have access to `project` data in their URL templates. ### Resource Links Resource links appear in individual resource summaries (pods, deployments, services, etc.). These links can reference `resource`, `application`, `cluster`, and `project` data in their URL templates. ## Adding a Deep Link To add a deep link: 1. Click + Add Deep Link under the appropriate section (Application Links, Project Links, or Resource Links). 1. Enter a **Title** for the link (this is displayed in the UI). 1. Enter the **URL** template for the link. 1. Click Save. ## Presets The Akuity Platform provides preset configurations for common integrations. Click the + Datadog button and select your Datadog region to quickly add pre-configured deep links: - US1 - East - US3 - West - US5 - Central - EU1 - Europe - AP1 - Japan - US1-FED (FedRamp) --- ## Global Projects Global projects allow you to define project-level restrictions (source repositories, destination clusters/namespaces, and cluster resource allow/deny lists) that are automatically inherited by other projects in your Argo CD instance. Any project matching the label selector of a global project will have those restrictions applied on top of its own configuration. For more details on how global projects work, see the [Argo CD Global Projects documentation](https://argo-cd.readthedocs.io/en/stable/user-guide/projects/#global-projects). ## Configuring Global Projects Global project settings are configured using a YAML editor in the Akuity Platform UI. ![global-projects](/img/global_projects_01.png) 1. Navigate to Argo CD → _your instance_ → Settings → Global Projects. 2. Enter your global project configuration in the YAML editor. The value is a list of entries, each specifying a `projectName` (an existing Argo CD project) and a `labelSelector` that determines which projects inherit its restrictions. ```yaml - projectName: my-global-project labelSelector: matchExpressions: - key: environment operator: In values: - production ``` 3. Click Save to apply the configuration. Any project whose labels match the `labelSelector` will inherit the source repo restrictions, destination restrictions, and cluster resource allow/deny lists defined on `my-global-project`. --- ## Crossplane Extension ![Crossplane extension](/img/crossplane_extension_example.png) If you are managing your Crossplane resources using Argo CD then you can leverage this built-in Crossplane extension in Akuity Argo CD instance. This extension will help Argo CD track Crossplane resources. It will update the health and sync status. On top of that, you will able to see those details directly inside Argo CD UI. This extension will ask you to provide your Crossplane Custom Resource Definition group name glob pattern and that is all you need to configure it. ## Enable Crossplane Extension - Navigate to your Argo CD instance settings in Akuity Platform. Argo CD → _your instance_ → Settings → Extensions. - Click on Install in Crossplane extension. It will open configuration modal which you can edit at any point. - There will be a default CRD group names glob pattern. You can add your custom Crossplane CompositeResourceDefinition group name as well. > Note: The glob pattern will be used in Argo CD UI and Argo CD resource customization config, make sure it is in format that is detected in both places. For example if group name is `.example.com` then use `*.example.*` - Click Ok. --- ## ApplicationSet Extension Argo CD [ApplicationSets](https://argo-cd.readthedocs.io/en/stable/user-guide/application-set/) are a powerful tool for automating the creation and management of Argo CD Applications across multiple clusters and environments. ApplicationSets do this by templating Application manifests, which enables GitOps at scale. However, managing ApplicationSets, which is traditionally done via YAML manifests and command-line interfaces, often becomes cumbersome – especially during troubleshooting. Figuring out why expected Applications weren't generated requires manually checking of status fields, digging through controller logs, and inspecting Kubernetes events. There is no way to do this through the core Argo CD UI, making the process even more difficult. The ApplicationSets extension provides users with ease-of-use and an intuitive interface for ApplicationSet management. Key capabilities including: - **Full CRUD Management**: Create, view, edit, and delete ApplicationSets. - **Status Visualization**: Easily view the aggregated sync and health status of generated Applications. - **Live Previews**: Instantly preview the applications an ApplicationSet will generate or modify before saving changes. ## Enable ApplicationSet Extension - Navigate to your Argo CD instance settings in Akuity Platform. Argo CD → _your instance_ → Settings → Extensions. - Click on Install in ApplicationSet extension, and click Confirm to confirm the installation. ![ApplicationSet extension on AKP](/img/appset_extension_01.png) ## Manage ApplicationSets in the Argo CD UI The new ApplicationSet management capabilities include a dedicated ApplicationSets section on the Argo CD navigation in the Akuity Platform. From the UI, you can perform full CRUD (Create, Read, Update, Delete) operations just like you would for regular Applications. This brings ApplicationSet management into the same intuitive workflow you already use for your Argo CD applications. ### Create & Preview ApplicationSets in the UI You can create ApplicationSets by navigating to the ApplicationSets section, and click + CREATE. ![Create ApplicationSet](/img/appset_extension_02.png) Then define your ApplicationSet in the Manifest editor: ![Define ApplicationSet](/img/appset_extension_03.png) Before committing, click SAVE AND PREVIEW to see exactly which Applications your current definition will generate. This immediate feedback loop helps catch errors in generators or templates early, ensuring you deploy what you intend. ![Preview ApplicationSet](/img/appset_extension_04.png) ### View Generated Application Status Once your ApplicationSet is created, understanding the state of the applications it manages is simple. Select the ApplicationSet and go to the LIVE STATUS tab. This provides a consolidated view, showing the aggregated sync and health status of all generated applications. ![View ApplicationSet Status](/img/appset_extension_05.png) ### Modify, Preview, and Apply Changes in the UI If you want to modify the ApplicationSet, go to the EDIT AND PREVIEW tab. Here you can modify the manifest directly. For instance, let's change the `spec.template.spec.source.path` from `guestbook` to `kustomize-guestbook`, remove `dev` cluster and add `stg` cluster: ![Modify ApplicationSet](/img/appset_extension_06.png) After editing, click the SAVE AND PREVIEW sub-tab within EDIT AND PREVIEW. It instantly refreshes, showing the diff of applications that will be generated based on your modified manifest. This lets you confirm the change (like the updated path) has the desired effect before you apply it. Once confident, click APPLY to save the changes. The preview updates instantly, showing the 'path' change for the generated Applications before applying. ![Show ApplicationSet Change](/img/appset_extension_07.png) --- ## Settings --- ## Creating Addons Cluster addons can be created in two ways: 1. Marketplace wizard 2. Manually creating the repository Before creating cluster addons, ensure that you have installed the [addons extension](./index.mdx#addons-extension) and connected the addons Git repository. ## Step 1: Install Addons Extension To use the cluster addons you must install cluster addons extension on your Argo CD instance. To do so: 1. Navigate to your Argo CD instance settings and enter Extensions section. 2. Click the Install button on Cluster Addons tile. You will see a modal, where you can add users and group roles that have access to the addons extension inside Argo CD. ![Install Addons Extension](/img/addons_install_extension.png) 3. After configuring and clicking OK button the extension will be installed. ## Step 2: Add Addons Repository The [addons repository](./index.mdx#addon-repository) contains the addons for the cluster. There are two ways to add an addons repository: ### Option 1: Connect Existing Addons Repo If you already have a repository added to Argo CD that you want to use for cluster addons: 1. Go to your ArgoCD instance settings on Akuity Platform and enter Addons section. You can also access this page from the addons list in ArgoCD extension. 2. Click the Connect Addons Repo button. ![Connect Addons Repo](/img/addons_connect_existing.png) 3. In the modal that opens, select the repository from the list of existing Argo CD repositories and enter the branch, then click Connect. :::important The repository credentials must have **write access** to the repository for features like marketplace operations, manifest source updates, and deletions to work properly. ::: ### Option 2: Add New Addons Repo If you want to create a new repository from scratch: 1. Go to your ArgoCD instance settings on Akuity Platform and enter Addons section. You can also access this page from the addons list in ArgoCD extension. 2. Click the Add Addons Repo button. ![Add Addons Repo](/img/addons_add_new.png) 3. In the modal that opens, you'll see two tabs: - **Form**: Use the form interface to configure the repository - **JSON Editor**: Use JSON format for advanced configuration 4. In the Form tab, configure the repository connection: - **Connection Method**: Select your preferred connection method from the dropdown (e.g., HTTPS, SSH, etc.) - **Repository URL**: Enter the Git repository URL - **Credentials**: Provide authentication details based on your connection method: - For HTTPS: Username and password/token - For SSH: SSH private key - **Additional Settings**: Configure any other required parameters specific to your repository 5. Click Add to create the repository. The corresponding repository will be automatically added to Argo CD and connected as a cluster addon repository. ## Step 3: Create Addons Once the [addons repository](./index.mdx#addon-repository) is connected, you can create cluster addons using the marketplace wizard or manually. ### Marketplace The Cluster Addons Marketplace is a curated catalog of ready-to-deploy applications for Kubernetes clusters. With just a few clicks, users can deploy multiple addons to all their configured clusters with no complex setup required. From monitoring to security and developer tools, the marketplace streamlines deployments and boosts efficiency. To create a cluster addon using the marketplace wizard, follow these steps: 1. Ensure that the [Cluster Addons Extension is installed](#step-1-install-addons-extension) and [addons repository is connected](#step-2-add-addons-repository). 2. Go to your deployed Argo CD instance and enter Cluster Addons section. 3. Click Explore Addon Marketplace button. ![Explore Addon Marketplace](/img/addons_addons_list_explore.png) 4. View the list of available addons. Choose the addon you wish to add, click the Add button, and then click Next. ![Install Marketplace Addon Step 1](/img/addons_marketplace_step_1.png) 4. In the Edit packages details step, review the marketplace dependencies that have been added: - **Marketplace dependencies**: Change the version of the added dependencies. - **Custom dependencies**: Add custom dependencies if required (provide Name, Version, and Repository URL). Click Next. 5. In the Choose repository and add metadata step, provide: - **Repository**: Choose the Git repository and branch where you want to add the addon. - **Helm chart metadata**: Enter the Name, Version, and Description. - **Additional overrides**: Add any [overrides](./index.mdx#overrides) if needed (for example, cluster or environment overrides). Click Finish. 6. The addon is created in the selected repository. ![Marketplace Git Repo](/img/addons_marketpalce_installed.png) #### Reinstalling Marketplace Addons If an addon is deleted from the Git repository, you can reinstall it to update the addon in the cluster. You can also delete marketplace addons directly from the platform interface. :::note When deleting a marketplace addon from the platform, the action will delete the addon marketplace installation data (which can be used for addon reinstallation) and also delete Git repository data related to this addon name. ::: Follow these steps: 1. Go to the Addons tab in your ArgoCD instance and look for the addon you wish to reinstall. These addons will be marked with a Uninstalled status. 2. Find the addon you wish to reinstall and click the Reinstall button. 3. You will see a confirmation modal that allows to also change the version of reinstalled dependencies. Click Reinstall again to confirm. ![Marketplace Reinstall](/img/addons_marketplace_reinstall.png) ### Manually Creating Addons :::info INFO Cluster Addons supports two types of manifest generation tools: **Helm charts** and **Kustomize** overlays. Choose the option that best suits your deployment requirements. ::: To manually create cluster addons, follow these steps: 1. Ensure that the [addons repository](./index.mdx#addon-repository) is connected. 2. Organize your repository with the following directory structure: ``` ├── addons │ ├── │ │ ├── Chart.yaml │ │ ├── values.yaml │ ├── │ │ ├── kustomization.yaml │ │ ├── .yaml │ │ ├── .yaml ├── clusters │ ├── │ │ ├── │ │ │ ├── values.yaml │ │ ├── │ │ │ ├── kustomization.yaml ├── envs │ ├── │ │ ├── │ │ │ ├── values.yaml │ │ ├── │ │ │ ├── kustomization.yaml ``` - **addons**: Contains the addons that can be installed in the cluster. - **clusters**: Contains cluster-specific [overrides](./index.mdx#overrides) for the addons. - **envs**: Contains environment-specific [overrides](./index.mdx#overrides) for the addons. 3. Once the repository is configured with the required addons, they will be available in the Cluster Addons section of your deployed ArgoCD instance. In the next section, we will see how to install the addons in the cluster. --- ## Deploying Addons Once you have created the addons, you can enable (deploy) them in your cluster. Before deploying, you must first configure the addon. ## Step 1: Configure Addon To configure an addon, follow these steps: 1. In your deployed ArgoCD instance go to Cluster Addons section, and click on the addon you wish to configure. ![Addons Tab](/img/addons_list_click_tile.png) 2. In the addon details view, click the Config button. ![Addon Details](/img/addons_click_config.png) 3. Configure the addon options: 1. **Template Name**: The templated name of the addon. 2. **Template Namespace**: The templated namespace where the addon will be deployed. 3. **Template Project**: The templated project where the addon will be deployed. :::note Template Syntax You can use the following allowed template expressions to dynamically configure your addon: - **Addon Fields:** - `{{ .addon.name }}` — The name of the addon. - `{{ .addon.type }}` — The type of the addon (e.g., "helm", "kustomize"). - **Cluster Fields:** - `{{ .cluster.name }}` — The cluster's name. - `{{ .cluster.namespace }}` — The cluster's namespace. - `{{ .cluster.labels }}` — The cluster's labels (use `{{ .cluster.labels.key }}` to access specific labels). - `{{ .cluster.annotations }}` — The cluster's annotations: - Use `{{ .cluster.annotations.key }}` to access specific annotations - Use `{{ .cluster.annotations["example.com/xyz"] }}` for keys with dots/slashes - **Note**: Array values cannot be accessed by index. The entire array must be set as a value. ::: 4. **Creation Options**: Configure the creation details for the addon. 5. **Auto Sync Options**: - **Auto Sync**: Enable automatic synchronization of the addon. - **Auto Heal**: Enable automatic healing of the addon. - **Prune Resources**: Enable automatic pruning of resources. 6. **Sync Options**: - **Skip Schema Validation**: Skip schema validation. - **Auto-Create Namespace**: Automatically create the namespace if it does not exist. - **Prune Last**: Prune the last remaining resources. - **Apply Out of Sync Only**: Apply changes only when the addon is out of sync. - **Respect Ignore Differences**: Respect the ignore differences configuration. - **Server-Side Apply**: Use Kubernetes Server-Side Apply. - **Replace**: Replace existing resources during sync. 7. **Prune Propagation Policy**: Set the prune propagation policy. 8. **Deployment Options**: Configure the addon deployment details based on its type: - **Helm Options**: - **Source Values**: Specify YAML paths to extract specific values from your Helm values file. These paths define which configuration values will be managed by the addon system. For example: ``` # Example YAML paths to extract specific values: image.tag replicaCount ingress.host resources.limits.memory ``` The system will extract these values from your values.yaml file and allow you to override them per cluster or environment through Manifest Source updates. - **Release Name Template**: Define the release name template for Helm releases. This is useful for distinguishing between the same addon deployed to different clusters: ``` # Examples: {{ .addon.name }}-{{ .cluster.name }} {{ .cluster.name }}-{{ .addon.type }} {{ .cluster.annotations["example.com/xyz"] }}-{{ .addon.name }} # For keys with dots/slashes ``` - **Kustomize Options**: - **Name Prefix Template**: Define the name prefix template for Kustomize resources. This helps avoid naming conflicts across clusters: ``` # Examples: {{ .cluster.name }}-{{ .addon.name }} {{ .addon.name }}-{{ .cluster.labels.environment }} ``` - **Name Suffix Template**: Define the name suffix template for Kustomize resources: ``` # Examples: {{ .addon.name }}-{{ .cluster.name }} {{ .addon.name }}-{{ .cluster.labels.region }} ``` 9. **Filters**: Control which clusters receive the addon: - **All Clusters**: Deploy the addon to all connected clusters. - **Selected Clusters**: Deploy the addon to selected clusters based on name and label filters. 4. Click Save to store the configuration. ![Addon Configuration](/img/addons_addon_config.png) ## Step 2: Enable/Deploy Addon After configuring the addon, enable (deploy) it in your cluster by following these steps: 1. In the Cluster Addons extension, select the addon you wish to enable. ![Addons Tab](/img/addons_list_click_tile.png) 2. In the addon details view, click the Enable button. Confirm the action by clicking Enable in the confirmation dialog. ![Addon Details](/img/addons_enable.png) 3. Navigate to the Summary tab for your addon. Here, you can view the current sync status. If auto-sync is not enabled, click the Sync button to synchronize the addon with your cluster. ![Addon Application](/img/addons_sync.png) 4. The addon will now be deployed in your cluster. :::note Enable Kustomize To use Kustomize for incorporating Helm charts in your addons, enable Kustomize in your ArgoCD instance settings as follows: 1. Open your instance settings and click on the Manifest Generation tab. 2. In the Kustomize section, enable the Enabled option and add the following build options: ``` --enable-helm --helm-kube-version=1.30 ``` 3. Click Save to apply the settings. ![Addon Application](/img/addons_enable_kustomize.png) ::: ## Cluster Customization You can patch the application spec of an addon to make cluster-specific changes. To patch the application spec, follow these steps: 1. In the Cluster Addons extension on your deployed Argo CD instance, select the addon you wish to patch. 2. Go to the Cluster Customization tab. 3. Click on the New Customization button to add a new patch. ![Addon Application](/img/addons_add_customization.png) 4. Select the target cluster, enter the patch details, and click Add to apply the patch. ![Addon Application](/img/addons_cluster_customization.png) ## Update Manifest Source You can update the [manifest source](./index.mdx#manifest-source) for an addon to implement environment or cluster-specific changes. This is where you can override the base configuration defined in the **Deployment Options** for specific clusters or environments. :::note Deployment Options The **Source Values** (YAML paths) configured in Deployment Options define which configuration values from your Helm values file will be managed by the addon system. The Manifest Source updates allow you to override these specific values for different clusters or environments, providing fine-grained control over your addon deployments. ::: ### Helm Addon Manifest Source Updates For Helm addons, you can update: 1. **Values Override**: Override specific values that were defined as YAML paths in the Source Values configuration. The system will update your values.yaml file with these overrides. 2. **Chart Dependencies**: Update chart dependency versions. ![Helm Addon Settings](/img/addons_helm_override.png) ### Kustomize Addon Manifest Source Updates For Kustomize addons, you can update: 1. **Images**: Update container image configurations including name, new name, tag, and digest. 2. **Helm Charts**: Update Helm chart dependencies used by Kustomize. ![Kustomize Addon Settings](/img/addons_kustomize_override.png) ### How to Update Manifest Source To update the manifest source, follow these steps: 1. Go to Cluster Addons section on your deployed Argo CD instance. 2. Select the addon you want to update and enter its details. 3. Navigate to the Manifest Source tab. 4. Click on the Settings icon next to the manifest source you wish to update. ![Addon Application](/img/addons_manifest_source.png) 4. Update the configuration based on your addon type: - **For Helm**: Update values and chart dependencies - **For Kustomize**: Update images and Helm chart dependencies 5. Click Update to apply the changes. ![Addon Application](/img/addons_manifest_source_update.png) In this way, you can deploy and manage addons in your cluster using Argo CD. In the next section, we will cover how to delete addons from the cluster. --- ## Deleting Addons You can delete installed addons from your cluster either individually or all at once. There are two ways to delete addons: 1. **UI-based deletion** - Delete addons directly from the [Addons Extension](./index.mdx#addons-extension) 2. **Manual deletion** - Delete addons manually from your Git repository ## Delete a Single Addon ### Option 1: UI-based Deletion To delete a single addon using the [Addons Extension](./index.mdx#addons-extension) interface: 1. Go to the Cluster Addons section in your deployed ArgoCD instance. 2. Click on the specific addon you want to delete. 3. In the addon details view, click the three-dot menu (⋮) in the top right corner. 4. Select Delete from the dropdown menu. ![Addons Deletion](/img/addons_delete.png) 5. Confirm the deletion when prompted. The addon will be automatically removed from your Git repository and uninstalled from the cluster. ### Option 2: Manual Deletion To delete a single addon manually: 1. Delete the addon from your Git repository. 2. Go to the Cluster Addons section in your deployed Argo CD instance. The addon should no longer be listed. :::note Note It may take a while to sync addon deletion from your repository to our data. You may speed this up by using Refresh button in Argo CD instance addon settings. ::: ## Delete All Addons To delete all addons from a repository at once, follow these steps: 1. Go to the Argo CD instance settings and enter Addons section. 2. Click on the Delete button next to the repository you want to remove. ![Addon Application](/img/addons_delete_all.png) 3. All addons from the repository will be deleted from your cluster. :::note Note Be aware that an addon may still appear if its child applications are stuck in a deletion state. This can occur due to an inactive cluster or issues with resource deletion. In such cases, ensure that the target clusters are live and resolve any deletion issues. Alternatively, you can enable the non-cascade deletion option in the addon configuration to unblock the deletion; however, related resources might continue to be deployed on the clusters. ::: --- ## Cluster Addons _Streamlined Multi-Cluster Application Management_ Cluster Addons is a comprehensive deployment orchestration feature that enables operators to define, version-control, and propagate standardized application manifests across multiple Kubernetes clusters. This GitOps-native solution maintains deployment manifests in git as the single source of truth while providing advanced filtering capabilities for target cluster selection, streamlining the entire process of managing and bootstrapping clusters effortlessly. This product makes it easier to manage your Kubernetes cluster add-ons with an easy-to-use interface, which saves time and effort when bootstrapping a new cluster and keeping existing cluster add-ons up to date. Key Capabilities: - **Centralized Addon Repository**: Maintain a curated library of deployment templates for commonly used applications with version control and change history - **Flexible Deployment Patterns**: Target specific clusters using rich filtering expressions based on labels, names and other metadata - **Customization Layers**: Apply environment/cluster specific overrides while preserving the core application manifest definition - **Addon Marketplace Integration**: Discover and implement pre-configured solutions from the community or trusted vendors - **GitOps Workflow**: Leverage existing Git infrastructure for change tracking, approvals, and audit compliance - **Declarative Configuration**: Define both the addon content and its target scope through simple YAML definitions - **Automated Provisioning**: Seamlessly bootstrap new clusters with essential applications upon registration to the platform, ensuring immediate operational readiness. - **Supports Multiple Manifest Generation Tools**: Configure deployments using either Helm charts or Kustomize overlays, according to your preference. ## How Cluster Addons Differs from ApplicationSet While both tools can manage multiple applications across clusters, the Akuity Cluster Addons provides significant advantages for cluster add-on management. Unlike ApplicationSet, which requires manual YAML configuration and offers basic templating capabilities, Cluster Addons provides a UI-driven interface with structured repository organization, multi-level customization overrides (environment, cluster, and application-specific), comprehensive health monitoring and sync tracking. Cluster Addons is specifically designed for cluster infrastructure and operational tools, offering simplified workflows that reduce configuration complexity while providing advanced operational insights that ApplicationSet lacks. ## Glossary - **Addon** : A reusable application template that can be deployed to multiple clusters. Addons are defined in a Git repository and can be customized for different environments. - **Addons Extension**: An Argo CD UI extension which provides access to the Cluster Addons feature. - **Addon Repository**: A Git repository that contains the definitions and configurations for one or more addons. This repository serves as the source of truth for addon deployments. - **Addon Application**: The ArgoCD application that represents the addon in the cluster. It is created based on the addon definition and is responsible for managing the deployment of the addon. - **Addon Marketplace**: A curated collection of pre-configured addons that can be easily deployed to clusters. The marketplace provides a user-friendly interface for discovering and implementing addons. - **Addon Configuration**: The settings and parameters that define how an addon is deployed, including the target clusters, deployment options, and any customizations. - **Addon Filters**: Criteria used to determine which clusters an addon should be deployed to. Filters can be based on labels or names. - **Manifest Source**: The source of the deployment manifests for an addon, which can be updated to implement environment or cluster-specific changes. - **Addon Dependencies**: Other applications or components that an addon relies on for proper functionality. Dependencies can be specified in the addon configuration. - **Overrides**: Custom configurations applied to an addon deployment to modify its behavior or settings. Overrides can be used to tailor the addon for specific environments or clusters. - **Cluster Customization**: The process of applying specific configurations or patches to an addon deployment for a particular cluster. This allows for tailored deployments while maintaining a common base definition. --- ## Features ## Server Side Pagination Server-side pagination significantly enhances the performance of the Argo CD frontend and extends its scalability to support tens of thousands of applications. For more details, check out the blog post: [Argo CD Ultimate Scalability](https://akuity.io/blog/argo-cd-ultimate-scalability). This feature is enabled by default in Akuity Argo CD and does not require additional configuration. ## Argo CD Application Resource Filtering The Argo CD Application Resource Filtering feature enables the application of fine-grained filters to Kubernetes resources retrieved from the configured Git or Helm repository. The feature is useful to exclude specific resources from the application sync process without making changes in the deployment repository. The feature introduced new field `customizations` in the `source` section of the Application CRD. The field allows to exclude or include resources based on their group, kind, name or namespace. ```yaml spec: source: # new section that allows to customize the delivered set of resources customizations: # exclude allows to exclude some resources based on their group, kind, name or namespace # by default nothing is excluded exclude: # the example below excludes all resources from the 'apps' group - group: 'apps' kind: '*' # include allows to include only some resources based on their group, kind, name or namespace # by default everything is included include: # the example below includes only resources from the 'RDS' kind - group: '*' kind: 'RDS' name: '*' namespace: '*' ``` The following example demonstrates how to exclude all `Deployment` resources from the application sync process: ```yaml apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: guestbook spec: destination: namespace: default server: https://kubernetes.default.svc project: default source: customization: exclude: - kind: Deployment path: guestbook repoURL: https://github.com/argoproj/argocd-example-apps targetRevision: HEAD ``` ## Application Set Applications Filtering The ApplicationSet Applications Filtering feature allows you to apply additional filters to the list of applications generated by an [ApplicationSet](https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/). The functionality is useful in case when filtering logic is too complex and cannot be implemented at the ApplicationSet [generators](https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Generators/) level. The feature introduced new field `filter` in the `spec` section of the ApplicationSet CRD: ```yaml apiVersion: argoproj.io/v1alpha1 kind: ApplicationSet metadata: name: guestbook-app-set spec: generators: ... template: ... # a new section that allows to filter out generated applications filter: expressions: # simple filter by name - app.metadata.name == "us-west-1-guestbook" # filter by managed resource: filter out applications that don't have any resources - len(appInfo.GetManagedResources()) > 0 # optional: skip applications that cause filter evaluation errors skipOnFailure: false ``` The `filter` allows defining a list of expressions that are evaluated against each generated application. The expressions are powered by [expr-lang](https://expr-lang.org/) libarary. The following variables are available in the expressions: * `app` - represents the generated application. * `appInfo.GetManagedResources()` - function that returns a list of Kubernetes resources managed by the generated Application. --- ## Akuity Argo CD Akuity Argo CD is a tailored version of Argo CD, maintained by Akuity, and enhanced with advanced features and improved stability. You can switch an existing Argo CD instance to the Akuity version via the [General](../30-settings/01-general.md) tab on the settings page in the Akuity Portal. To make the switch, select a version marked with the `-ak` postfix. ![Akuity Argo CD](/img/ak-argocd-version.png) ## Argo CD CLI In addition to the standard Argo CD CLI, Akuity provides its own version designed specifically for the Akuity version of Argo CD, which supports several [features](20-features.md) unique to the Akuity Platform and unavailable in upstream Argo CD. All images provided via the Argo CD UI will be based on the latest patched version for each minor release. :::note The first download listed will always be the open-source (OSS) version of the CLI. ::: To download: 1. Navigate to the Argo CD UI → Documentation. 1. Then choose your preferred OS/Arch. ![Akuity Argo CD CLI](/img/akuity-argocd-cli.png) --- ## Managing Argo CD Instances --- ## Create an Kargo Instance ## Account Setup :::info For access to the Akuity Platform please [create an Akuity user account](https://hubs.li/Q02l2XGR0). After completing the registration process, activate your account using the link sent to your email. ::: After registering and activating your account, if this is your first time using the platform, you must also create an organization: 1. Click the create or join link. 2. Click + New organization in the upper right hand corner of the dashboard. 3. Name your organization following the rules listed below the Organization Name field. ## Create an Kargo Instance 1. Navigate to Kargo. 2. Click + Create in the upper right hand corner of the dashboard. 3. Name your instance following the rules listed below the Instance Name field. 4. (Optionally) Choose the Kargo version you want to use. 5. Click Create. It will take several seconds to create your new Kargo instance (Progressing status next to your new instance's name), so please be patient. Continue on to the [next section](./20-connect-kargo-agent.mdx) to learn about connecting your new Kargo instance to an agent. --- ## Connect a Kargo Agent After your new Kargo instance is created successfully (Healthy status next to your new instance's name): 1. Navigate to Kargo → _your instance_ → Agents. 1. Click + Register an agent to add a Kargo Agent. 1. Input your Agent Name. 1. **Choose agent hosting option**: Kargo agents may be hosted and run on the Akuity Platform control-plane, or they can be self-hosted and installed into an on-premises cluster behind corporate firewalls. **Select the self-hosted agent option** if Kargo needs to run Kubernetes Jobs as part of testing/verification, or if Kargo needs to interface with private, self-hosted services including: - private Git servers - internally accessible metric providers (e.g. self-hosted Prometheus) - self-managed Argo CD **Otherwise**, if using public git providers (GitHub, GitLab), public metric providers (DataDog, CloudWatch, NewRelic), and Akuity Platform-managed Argo CD, the agent can be hosted/managed by the Akuity Platform. :::caution AnalysisTemplates/AnalysisRuns that use Kubernetes Jobs will never complete if the agent is Akuity Platform-managed. You must use a self-hosted agent if your verifications require Kubernetes Jobs. ::: 1. (Optionally) Kargo can interface with Argo CD instances to sync applications, reflect application health, and verify successful sync operations during promotion. To connect your agent to an Argo CD instance managed by Akuity Platform, select the name of the instance in the _Akuity Managed Argo CD_ option. If this agent is connecting to a self-hosted Argo CD, leave this unselected and install the agent into the cluster where Argo CD is running. 1. (Optionally) You can choose to set your agent to be the default agent by setting _Set as Default Shard_. It is by default set to true for the first agent you connect but you can override it by setting a different agent as default later. :::tip To assign specific Stages to this agent (or any other agent), use the `spec.shard` field in your Stage manifests. See [Shards and Agents](../03-managing-instances/20-agents/30-shards-and-agents.md) for detailed information on using shards to control which agent reconciles your Stages. ::: 1. Click Connect. 1. If you opted for _Self-hosted Kargo Agent_ then you would need to click on the _Install_ option shown beside the newly created agent in the table. This will display the _Install Akuity Agent_ popup. Click Copy to Clipboard :::caution Before pasting the next command, make sure you're connected to the correct cluster. ::: Paste the copied command into your terminal and run it to apply the agent manifest. Alternatively, you can download the agent manifest and apply it manually inside your cluster. :::caution When uninstalling the self-hosted agent, remove it from the AKP Kargo agent list, then run the provided cleanup command in your cluster to ensure all resources are properly removed. Avoid deleting the namespace directly, as this may cause resources to remain stuck in the terminating phase. ::: After installing the agent into your Kargo Agent, you should see the agent listed in the Akuity dashboard with a green heart icon next to the agent name. If you chose to let Akuity manage the agent then you can skip the above steps. Now that your Kargo instance is connected to a Kargo Agent, move on to the [next section](./30-enable-admin-user.mdx) to learn about enabling remote access to your instance. --- ## Enable the Kargo `admin` Account :::note Kargo instances you create inside the Akuity Platform do not enable the `admin` user by default. ::: To enable the `admin` user on an Kargo instance: 1. Navigate to Kargo → _your instance_ → Settings → System Accounts. 1. Enable the Admin Account switch. 1. Specify a custom password and click Save Now that the `admin` user is enabled, move on to the [next section](./40-access-kargo-instance.mdx) to learn about accessing your Kargo instance. --- ## Accessing Kargo :::info If you have not already enabled the `admin` user for your instance, follow [these instructions](./30-enable-admin-user.mdx). ::: :::info You can find the instance URL for Kargo by visiting Kargo → _your instance_. It is found in the upper left hand corner of the screen, to the right of the instance name and health status. ![Kargo Instance URL](./kargo-instance-url.png) ::: ## Access the Kargo Dashboard 1. Click on the _instance-id_.kargo.akuity.cloud. 2. Log in with the username `admin` and the password set (or generated) while [enabling the `admin` user](./30-enable-admin-user.mdx). ## Access Kargo using the `kargo` CLI 1. Install the `kargo` CLI: **Linux or WSL** ``` arch=$(uname -m) [ "$arch" = "x86_64" ] && arch=amd64 curl -L -o kargo https://github.com/akuity/kargo/releases/latest/download/kargo-$(uname -s | tr '[:upper:]' '[:lower:]')-${arch} chmod +x kargo ``` :::note You will also need to move `kargo` onto your `PATH`. ::: **Windows w/ Powershell** ``` Invoke-WebRequest -URI https://github.com/akuity/kargo/releases/latest/download/kargo-windows-amd64.exe -OutFile kargo.exe ``` :::note You will also need to move `kargo.exe` onto your `PATH`. ::: 1. Log in by using the following command and following the prompts: ``` kargo login \ --admin \ --password ``` At this point, you're ready to use your Akuity-managed Kargo instance as normal. --- ## Getting Started(01-getting-started) --- ## DORA Metrics The DORA Metrics section inside the Akuity Platform Dashboard provides insights into the performance of your software delivery process. DORA (DevOps Research and Assessment) metrics are a set of key performance indicators that help organizations measure their software delivery capabilities. ## Accessing DORA Metrics To access the DORA Metrics section, navigate to the Akuity Platform Dashboard and select the desired Kargo instance. From there, you can find the Metrics section, which displays various metrics related to your software delivery performance. ![Kargo DORA Metrics](/img/kargo_metrics_1.jpg) ## Key DORA Metrics The DORA Metrics section includes the following key metrics: - **Deployment Frequency**: Measures how often an organization successfully releases to selected stage(s) in your environment. Higher deployment frequency indicates a more agile and responsive development process. - **Lead Time for Changes**: Measures the amount of time it takes a freightline to get into selected stage(s). Shorter lead times indicate a more efficient development process. - **Change Failure Rate**: Measures the percentage of deployments causing a failure in selected stage(s). Lower change failure rates indicate a more stable and reliable deployment process. - **Mean Time to Recovery (MTTR)**: Measures how long it takes an organization to recover from a failure in selected stage(s). Shorter MTTR indicates a more resilient and responsive incident management process. ## Filters You can filter the DORA Metrics by combining various parameters. The available filters include: - **Stage**: Select the stage(s) you want to analyze (e.g., Development, Staging, Production). - **Project**: Choose specific projects to focus on. - **Initiator**: Filter by the user who initiated the promotion. - **Interval**: Select the time range for the metrics (e.g., Day or Week). By utilizing these filters, you can gain deeper insights into your software delivery performance and identify areas for improvement. ## Events The DORA Metrics section also provides a list of events related to promotions and changes in your selected stage(s). This includes information about successful promotions, failed promotions, and recovery actions taken. Monitoring these events can help you understand the context behind the metrics and identify patterns or trends in your software delivery process. ![Kargo DORA Metrics Events](/img/kargo_metrics_2.jpg) Filters will be applied to the events list as well, allowing you to focus on specific projects, initiators, and time intervals. --- ## Akuity Platform Dashboard(10-dashboard) The [Akuity Platform dashboard](https://akuity.cloud) is where you provision, and manage all aspects of your Argo CD & Kargo instances. --- ## Advanced Settings(20-agents) --- ## General ### Auto Update - Toggle Auto Apply Changes off to prevent the agent from automatically upgrading its components. :::note[Manual Updates to the Akuity Agent] With auto upgrades disabled, users must apply the agent updates manually. To accomplish this, go to the Clusters menu for the Kargo instance and click Install Agent on the desired cluster, then run the provided command with the `kubectl` context set for the corresponding cluster. ::: ### Private Connectivity - The Private Connectivity setting controls how the agent connects to the Akuity Platform. Public connects over the public internet, while Private connects through an AWS interface endpoint in your VPC using AWS PrivateLink. See [Private Connectivity (AWS PrivateLink)](/akuity-portal/security/private-link) for the full setup guide. :::note Private requires a connected AWS account with an available PrivateLink connection. Akuity-managed agents always use public connectivity. ::: ### Agent Size :::note Agent size configuration is only available for self-hosted Kargo agents. ::: - In the Agent Size section, choose the size of your Akuity Agent. This selection only impacts the resources allocated to the Akuity Agent within your cluster and does not impact your billing in any way. | Agent Size | Controller Memory | Controller CPU | |------------|-------------------|----------------| | Small | 0.5GB | 0.25CPU | | Medium | 1GB | 0.50CPU | | Large | 2GB | 1CPU | | Auto | Auto | Auto | #### Kargo Controller Autoscaling (Auto) :::caution The **Auto** size for Kargo agents is an experimental, alpha-quality feature. ::: When you set an agent's size to **Auto**, the Akuity Agent continuously right-sizes the Kargo controller running in that cluster. If a pod is OOMKilled, the agent detects it immediately and scales up both memory and CPU resources. CPU and memory scale up when average usage exceeds **80%** of the current allocation, and scale down when it drops below **30%**, preventing flapping. ## Manifests Customization ### Akuity Custom Image Registry - Enter where to pull the agent image from using the Akuity Custom Image Registry field. The default registry is [`quay.io/akuity`](https://quay.io/repository/akuity/agent?tab=tags). ### Argoproj Custom Image Registry - Enter where to pull the Argo CD images from using the Argoproj Custom Image Registry field. The default registry is [`quay.io/argoproj`](https://quay.io/repository/argoproj/argocd?tab=tags). ### Kargo Custom Image Registry - Enter where to pull the Kargo images from using the Kargo Custom Image Registry field. The default registry is [`quay.io/akuity`](https://quay.io/repository/akuity/kargo?tab=tags). ### Custom CA Bundle - Use the Custom CA Bundle field to provide a PEM bundle of one or more CA certificates that the agent workloads should trust in addition to the well-known public CAs. This is typically needed when the agent runs behind a TLS-intercepting proxy (for example, Zscaler) or connects to Git repositories and registries that use certificates issued by a private CA. When a bundle is set, every agent workload combines it with the default trust store and mounts the result at `/etc/ssl/certs/ca-certificates.crt`, so all components — including `git` used during promotions — trust the additional CAs. Updating or clearing the bundle restarts the agent workloads automatically. :::note - A single certificate or a bundle of several certificates is accepted. All certificates must be valid (unexpired) PEM-encoded `CERTIFICATE` blocks. - New agents inherit the bundle configured in [`Agent Default Settings`](/kargo/managing-instances/settings/advanced/agent-default-settings), unless a bundle is provided when registering the agent. - Akuity-managed Kargo agents use internal service endpoints and do not support a custom CA bundle. ::: ### Kustomization - The Akuity Platform supports customizing the Akuity Agent manifests using a `Kustomization`. --- ## Credential Rotation(20-agents) The agent in each managed cluster contains several components which require credentials from the Akuity Platform. You can easily rotate credentials for those from the Akuity Platform. You can rotate the credentials one at a time. - To rotate the credentials of an individual agent, go to _your instance_ → agents tab → click on the three-dot button under Action column → Click on Rotate Credentials → Click on Confirm. ![Rotate Agent Credentials](/img/kargo_creds_rotation_01.jpg) This will trigger an update to the agent(s) in the background. > NOTE: If the agent has Auto Upgrade disabled, you must re-apply the manifest. --- ## Shards and Agents Kargo uses a sharding mechanism to distribute Stage reconciliation across multiple agents. Each agent has a name that serves as its shard identifier. Stages without a shard assignment are reconciled by the default shard agent. ## When to Use Shards Assign Stages to specific shards when: - **Verification requires in-cluster resources**: Stages with `AnalysisTemplates` that require Kubernetes Jobs must run on a self-hosted agent in the target cluster. - **Network isolation**: Stages need to access private services (private Git servers, self-hosted Prometheus, internal APIs) only accessible from specific clusters. - **Multi-cluster deployments**: Multiple agents across different clusters require Stages to be reconciled by agents in the correct cluster. - **Resource distribution**: Distribute the load of Stage reconciliation across multiple agents. ## Assigning Stages to Shards To assign a Stage to a specific agent shard, set the `spec.shard` field in your Stage manifest to the name of the agent: ```yaml apiVersion: kargo.akuity.io/v1alpha1 kind: Stage metadata: name: production namespace: my-project spec: shard: prod-selfhosted requestedFreight: - origin: kind: Warehouse name: my-warehouse verification: analysisTemplates: - name: health-check kind: ClusterAnalysisTemplate ``` :::important The `spec.shard` field is the source of truth for shard assignment. Kargo's webhook automatically syncs the `kargo.akuity.io/shard` label from this field. Do not set the label directly in your YAML files, as it will be automatically managed by Kargo. ::: ## Default Shard If a Stage does not specify a `spec.shard` field, it will be reconciled by the agent configured as the default shard. The first agent you connect to a Kargo instance is automatically set as the default shard. You can change the default shard later in the Akuity Platform dashboard. ## Example Configuration In a typical setup, most Stages run on the default shard (Akuity Platform-managed agent), while Stages with verification run on a self-hosted agent: ```yaml # Stage without verification - uses default shard apiVersion: kargo.akuity.io/v1alpha1 kind: Stage metadata: name: dev namespace: my-project spec: # No shard specified - uses default shard requestedFreight: - origin: kind: Warehouse name: my-warehouse --- # Stage with verification - uses self-hosted shard apiVersion: kargo.akuity.io/v1alpha1 kind: Stage metadata: name: staging namespace: my-project spec: shard: prod-selfhosted requestedFreight: - origin: kind: Warehouse name: my-warehouse verification: analysisTemplates: - name: integration-tests kind: ClusterAnalysisTemplate ``` ## Verifying Shard Assignment After applying a Stage with `spec.shard` set, verify the shard assignment using one of the following methods: 1. **Using the Kargo CLI**: ```bash kargo get stages --project ``` The output will show the shard column: ```text NAME SHARD CURRENT FREIGHT HEALTH PHASE dev abc123 Healthy Steady staging prod-selfhosted def456 Healthy Steady ``` 2. **In the Kargo UI**: Navigate to your project and view the Stage details. The shard information is displayed in the Stage metadata. 3. **Using kubectl**: The `kargo.akuity.io/shard` label is automatically set by Kargo's webhook: ```bash kubectl get stage -n -o json | jq -r '.metadata.labels."kargo.akuity.io/shard"' ``` --- ## Maintenance Mode(20-agents) Maintenance Mode allows you to temporarily exclude managed agents from health monitoring and alerting when performing planned maintenance activities. This feature helps prevent false alerts during scheduled maintenance windows while ensuring monitoring is automatically restored after the maintenance period. You maintain full control to disable maintenance mode at any time. The Kargo applications continue to work and promote normally. ## Enabling Maintenance Mode To enable maintenance mode for a managed agent: 1. Navigate to your Kargo instance → Agents tab. 2. Find the agent you want to put into maintenance mode. 3. Under the Actions column, click on the three-dot button. 4. Locate the Enable Maintenance Mode section. ![Maintenance Mode Section](/img/kargo_clusters_01.jpg) 5. Enter the expiration day and time for maintenance mode. This is the date and time when maintenance mode will automatically expire and monitoring will be restored. 6. Click Save to apply the changes. ![Maintenance Mode Modal](/img/kargo_clusters_02.jpg) Once enabled, the agent will be excluded from health monitoring and alerting. The 🔧 icon indicates that the agent is in maintenance mode. ![Agent in Maintenance Mode](/img/kargo_clusters_03.jpg) ## Disabling Maintenance Mode Maintenance mode can be disabled in the following ways: ### Automatic Expiration Maintenance mode will be automatically disabled after the expiration time that you set to ensure monitoring is restored. If maintenance activities require more time, you will need to manually re-enable maintenance mode. ### Manual Disabling To manually disable maintenance mode before the expiration time: 1. Navigate to the agent actions as described above. 2. Locate the Disable Maintenance Mode section. 3. Click Disable to apply the changes. ![Disable Maintenance Mode Modal](/img/kargo_clusters_04.jpg) --- ## Regenerate Manifests(20-agents) The **Regenerate Manifests** feature allows you to bump the agent generation, which triggers the agent to re-apply all manifests in the managed agent. This is useful when you need to force a refresh of the agent configuration or recover from inconsistent states. You can regenerate manifests for a single managed agent or multiple at once. - To regenerate manifests for multiple agents, go to _your instance_ → Agents tab → click refresh icon above the agents table. Either select All Agents or Selected Agents and click on Regenerate. ![Regenerate Manifests Multiple Agents](/img/kargo_clusters_05.jpg) - To regenerate manifests for an individual agent, go to _your instance_ → Agents tab → click on the three-dot button under Action column → Click on Regenerate Manifests → Click on Confirm. ![Regenerate Manifests Modal](/img/kargo_clusters_06.jpg) --- ## General Settings(30-settings) ## Change Version The version of a managed Kargo instance can be upgraded (or downgraded) easily using the Akuity Platform. 1. Navigate to Kargo → _your instance_ → Settings → General. 1. Under Instance, select your desired version. 1. Click Save. Once saved, the Akuity Platform will automatically update the instance. After the operation is complete, the instance will show a healthy status in the dashboard, indicating success. :::caution Changing the version of the instance will trigger an update of the Akuity Agent on all connected clusters. The operation is carried out by a temporary job executed in the agent's namespace. Automatic updates to the Akuity Agent can be disabled by default for all clusters on an instance and per cluster. See Disable Auto Upgrade in [Agent Advanced Settings](../20-agents/10-agent-advanced-settings.md). ::: :::note A similar job is used when modifying cluster options such as Agent size, Labels or Annotations, to automatically update the agent configuration in the connected clusters. ::: ## Global Namespace Settings The global namespaces are a list of Kargo Project namespaces that house credentials/service accounts made available to all Projects. This is useful for centrally managing shared service accounts which have access to all projects or shared credentials (such as read-only container image registry credentials) that would be used in multiple projects. ## Default Shard Agent The Default Shard Agent is a feature that allows you to designate a specific Akuity Agent to handle shard operations for your Kargo instance. The default agent will reconcile all Kargo Stages that are not assigned to a specific shard. ## Instance Termination Protection Instance termination protection prevents a Kargo instance from being accidentally deleted. When enabled, any attempt to delete the instance will be blocked until the protection is explicitly disabled. To enable termination protection: 1. Navigate to Kargo → _your instance_ → Settings → General. 2. Toggle the Enable Termination Protection switch. 3. Optionally, enter a message in the Instance Protection Notes field. This message is displayed to anyone who attempts to delete the instance, and can be used to explain why the instance is protected or who to contact for more information. 4. Click Save. ![Kargo Instance Termination Protection](/img/kargo_settings_instance_protection.jpg) --- ## SSO The Akuity Platform allows you to configure a single SSO provider for Kargo, such as Dex, OIDC, or any other supported providers, ensuring secure user access to your Kargo instance. The Akuity Platform supports the following SSO providers: - [Dex](https://dexidp.io/) - OpenID Connect (OIDC) :::info For more detailed information on Kargo SSO, please refer to the [documentation of OSS Kargo](https://docs.kargo.io/operator-guide/security/openid-connect). ::: Below are the steps to configure SSO for Kargo using Dex and Okta as an **example**. ## Configuring SSO 1. In your Kargo Instance, go to Settings. 2. In the left panel, search for Access and go to OIDC Config. ![SSO Settings](/img/kargo-sso-1.png) 3. Click on the Enabled toggle to enable OIDC and choose your desired `Type`. ![Connector Type](/img/kargo-sso-2.png) ## Okta ### Working SAML Configuration with Okta Below is an example Dex configuration for Okta: ```yaml connectors: - type: saml id: okta name: OKTA config: ssoURL: https://yourorganization.oktapreview.com/app/yourorganizationsandbox_appname/sso/saml redirectURI: https://.kargo.akuity.cloud/dex/callback usernameAttr: name emailAttr: email groupsAttr: groups caData: ``` Reference: [https://dexidp.io/docs/connectors/saml/](https://dexidp.io/docs/connectors/saml/) ### Steps to configure Okta for SSO with SAML: 1. In your Okta Admin Dashboard, Go to Applications -> Applications -> Create App Integration ![Create App Integration](/img/sso_okta_1.png) 2. Select SAML 2.0 and click Next ![SAML 2.0](/img/sso_okta_2.png) 3. Give your application a name and click Next ![App Name](/img/sso_okta_3.png) 4. In Configure SAML section, enter the following details: - Single sign on URL: `https://.kargo.akuity.cloud/dex/callback` - Audience URI (SP Entity ID): `https://.kargo.akuity.cloud/dex/callback` - In the Attributes Statements section add : | Name | Name format | Value | |-------------|-------------|----------------| | email | Unspecified | user.email | | name | Unspecified | user.fullName | - In the Group Attribute Statements section add the following, (you can modify the group regex according to your needs) : | Name | Name format | Filter | |-------------|-------------|----------------------| | groups | Unspecified | Matches regex : `.*` | - Click Next and Finish 5. Go to the Application details page, select Sign On tab and then find and click the View SAML setup instructions button on the right side. ![SAML Setup](/img/sso_okta_6.png) 6. Copy the Identity Provider Single Sign-On URL and use it for ssoURL: in the Dex config. ![IDP URL](/img/sso_okta_10.png) 7. Download the Certificate and base64 encode it, then apply it to your Dex config. ![Certificate](/img/sso_okta_11.png) --- ## External Access(20-security-and-access) All external access settings can be located by navigating to Kargo → _your instance_ → Settings → External Access. ## Custom Domain ### Akuity Subdomain By default, each Kargo instance's UI will be accessible at `.kargo.akuity.cloud`, however, the Akuity Platform does permit you to set a custom domain prefix for each Kargo Instance. To customize this: 1. Change the value of the Akuity Subdomain field. 2. Click Save. ![Kargo Akuity Subdomain](/img/kargo_external_access_1.png) ### Fully Qualified Domain Name If you have a custom domain that you would like to use, you can set up a CNAME record to point to the Akuity Platform's domain. To do this: 1. Create a CNAME record in your DNS provider that points to `.kargo.akuity.cloud`. 2. Change the value of the Fully Qualified Domain Name field to your custom domain. 3. Click Save. ## IP Allow List By default, each Kargo instance is accessible by clients with any IP address, however, this can be narrowed to a specific list of IP addresses or CIDR ranges. To customize this: 1. Under IP Allow List, click + Add New and complete the IP Address and Description (optional) fields. * Repeat this step as necessary. 2. Click Save. ![Kargo IP Allow List](/img/kargo_external_access_2.png) To restore access from any IP address, simply remove all entries from the list. ## Private Connectivity Organizations with AWS PrivateLink enabled can take the Kargo instance off the public internet entirely by switching Private Connectivity to Private. This requires a connected AWS account and is mutually exclusive with the Fully Qualified Domain Name setting. See [Private Connectivity (AWS PrivateLink)](/akuity-portal/security/private-link) for the full setup guide. --- ## Kargo Secrets The Akuity Platform provides a way to synchronize secrets from your managed clusters to the Akuity-hosted Kargo instance. This capability is built in to the platform and requires no additional configuration to enable in your clusters. :::note This feature requires Agent version 0.5.75 or greater. ::: ## Syncing Secrets to the Kargo Control Plane In order to sync secrets to the control plane, you will need to have a Self-Hosted Kargo agent installed in your cluster. This can be done when registering an agent in the the "Agents" tab of the Kargo instance. ### Selecting which Secrets to Sync For security, secrets will not synced unless explicitly allowed by a control plane administrator. This can be done in the "Secrets" settings of the instance as shown below: ![Screenshot of the secret settings page](/img/secret-settings.png) Allowed secrets are configured by creating a Secret Source. A Secret Source has two fields, one of which must always be set: 1. **Cluster Selector**: A label selector for the clusters you wish to sync secrets from. The labels for the cluster are specified when connecting a cluster to the Akuity Platform. If this field is left empty, then the Label Selector will match secrets from all clusters. 2. **Secret Selector**: A [set-based label selector](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#set-based-requirement) for the secrets you wish to sync. If this field is left empty, then the Label Selector will match all secrets for all matching clusters :::tip You can use both Cluster and Label selectors to select specific secrets from specific clusters for more fine grained control ::: ### Creating Secrets :::warning If you create a secret syncing selector _after_ creating a secret in your Kubernetes cluster, the secret will not sync until Kubernetes resyncs or you reapply the secret. This is due to the limitation of the Kubernetes API, which only informs when a secret is updated/created. ::: To sync secrets from your managed clusters to the Kargo control plane, you need to create a secret in your managed cluster with the appropriate label. The Akuity agent will automatically detect these secrets and sync them to the Kargo control plane. You can create the secret in the Agent namespace within a managed cluster (`akuity` by default). In order to sync the secret, it must have two labels set. This first is a `kargo.akuity.io/secret-sync` label with a value of an existing Kargo project name or one of the cluster secrets namespaces (`kargo-cluster-secrets` in \<= 1.8 or `kargo-shared-resources` and `kargo-system-resources` in \>= 1.9). If the project does not exist, the secret will fail to sync. The second label is the [`kargo.akuity.io/cred-type` label](https://docs.kargo.io/operator-guide/security/managing-credentials#repository-credentials-as-secret-resources) which needs to be a value of `git`, `helm`, `image`, or `generic`, depending on the type of secret you are creating. If either of these labels are missing, the secret will be ignored and will not sync. If you used a label selector when creating the Secret Source, make sure that the secret also has the appropriate labels to match the selector. Here is an example secret that can be used to sync a generic credential: ```yaml apiVersion: v1 kind: Secret metadata: name: webhook-credentials namespace: akuity labels: # These labels are required to enable syncing of this secret kargo.akuity.io/secret-sync: "kargo-demo" kargo.akuity.io/cred-type: "generic" stringData: password: my-password username: my-username ``` :::note Because secrets are synced all from the Agent namespace, make sure to choose unique names for your secrets to avoid name collisions. ::: ### Updating Secrets Any changes to the secret will be automatically synced to the Kargo control plane. You can also change the project that the secret is synced to by updating the `kargo.akuity.io/secret-sync` label to a different project name. This will delete it from the old project and create it in the new project. ### Secret Ownership It is possible to have multiple clusters syncing secrets to the Kargo control plane. Please note that it is up to you as the user to make sure you use unique secret names when syncing to the same projects. If two clusters are attempting to sync a secret named `webhook-credentials` to the same project, the _first create wins_. The second secret will fail to sync with an error in the agent logs indicating that the secret already exists and isn't owned by the agent's cluster. --- ## Akuity Agent Default Settings(30-advanced) The Akuity Agent is a component installed into a managed cluster allowing it to be managed by a Kargo instance on the Akuity Platform. Every cluster agent which is installed into Kubernetes clusters will have a corresponding cluster entry in Kargo and will be available as a Kargo Application destination. ## Default Settings To apply the settings globally go to Kargo → _your instance_ → Settings → Agent Default Settings. :::note Modifications made here will be applied globally. Additional clusters added to your instance will inherit these settings by default, unless specified via [`Akuity Platform Declarative management`](/akuity-portal/automation/declarative-management). ::: ## Applying Changes When the Agent Default Settings are updated and Save is clicked, the changes will apply only to newly added clusters. To update both existing and future clusters, select Update All Agents. |Setting | Enabled by Default | |--------------------------------------------------------------------------------------------------------------|--------------------| |[`Auto Apply Changes`](/kargo/managing-instances/agents/agent-advanced-settings#auto-update) | Yes | |[`Private Connectivity`](/kargo/managing-instances/agents/agent-advanced-settings#private-connectivity) | No (Public) | |[`Akuity Custom Image Registry`](/kargo/managing-instances/agents/agent-advanced-settings#akuity-custom-image-registry) | No | |[`Argoproj Custom Image Registry`](/kargo/managing-instances/agents/agent-advanced-settings#argoproj-custom-image-registry) | No | |[`Kargo Custom Image Registry`](/kargo/managing-instances/agents/agent-advanced-settings#kargo-custom-image-registry) | No | |[`Kustomization`](/kargo/managing-instances/agents/agent-advanced-settings#kustomization) | No | |[`Custom CA Bundle`](/kargo/managing-instances/agents/agent-advanced-settings#custom-ca-bundle) | No | --- ## Credentials Akuity Platform supports configuring system-wide metric provider credentials that are used by Argo Rollouts for progressive delivery and canary deployments. ## Supported Metric Providers The following metric providers can be configured with credentials in the Akuity Platform: ### DataDog DataDog integration allows Argo Rollouts to query metrics from your DataDog monitoring infrastructure during canary analysis. **Configuration Fields:** - **Address**: The DataDog API endpoint URL (typically `https://api.datadoghq.com/` or your region-specific endpoint) - **API Key**: Your DataDog API key used for authentication - **Application Key**: Your DataDog application key for additional API access ### New Relic New Relic integration enables Argo Rollouts to fetch metrics and insights from your New Relic monitoring platform. **Configuration Fields:** - **Personal API Key**: Your New Relic personal API key for authentication - **Account ID**: Your New Relic account ID - **Region**: Your New Relic region (US or EU) - **Base URL (REST)**: New Relic REST API endpoint (e.g., `https://api.newrelic.com`) - **Base URL (Nerdgraph)**: New Relic Nerdgraph API endpoint (e.g., `https://api.newrelic.com/graphql`) ### InfluxDB InfluxDB integration allows Argo Rollouts to query time-series data from your InfluxDB instance. **Configuration Fields:** - **Address**: The InfluxDB server URL and port (e.g., `https://influxdb.example.com:8086`) - **Auth Token**: Authentication token for accessing InfluxDB - **Organization**: Your InfluxDB organization name ## Configuration To configure metric provider credentials: 1. Navigate to your Kargo instance in the Akuity Platform 2. Go to the Settings tab 3. Click on Credentials 4. Select the metric provider you want to configure & Enable it ![Credentials Settings](/img/credentials_01.jpg) 5. Enter the required credentials and configuration values 6. Save the configuration ![DataDog Configuration](/img/credentials_02.jpg) --- ## Argo CD UI in Kargo The Argo CD UI in Kargo is a built-in extension for Kargo Enterprise on the Akuity Platform. It lets you view Argo CD application details — sync status, health, resource trees, and more — directly inside the Kargo dashboard, without switching to a separate Argo CD window. When a Kargo stage is connected to an Argo CD shard managed by Akuity, an Argo CD button appears on that stage node in your project view. Clicking it opens an embedded Argo CD UI page within Kargo. :::caution This feature requires both your Argo CD instance **and** your Kargo instance to be managed by the Akuity Platform. Self-hosted Argo CD or self-hosted Kargo installations are not supported. ::: ## How to access the Argo CD UI No configuration is needed to use the embedded Argo CD UI. The Argo CD button appears automatically on any stage that is interacting with an Argo CD shard. 1. In the Kargo dashboard, navigate to Projects and open your project. 1. In the pipeline view, locate the stage that is connected to an Argo CD application. If the stage is interacting with an Argo CD shard, an Argo CD button is visible on the stage node. ![Kargo stage node with Argo CD button](../../../static/img/argo_in_kargo_btn.png) 1. Click Argo CD. You are taken to an Argo CD UI page embedded inside the Kargo dashboard. ![Embedded Argo CD UI inside Kargo](../../../static/img/argo_in_kargo_example.png) The embedded view shows the Argo CD application associated with that stage, including: * Application sync status and health * Live resource tree (Deployments, ReplicaSets, Pods, Services, and more) * Sync history and operation details * Resource manifests and events :::tip To open the full Argo CD dashboard for that application, click Open in Argo CD UI in the top-right corner of the embedded view. ::: ## Read-only access By default, the embedded Argo CD UI is **read-only**. You can view all application details, but write operations — such as syncing an application, deleting a resource, or triggering a rollback — will return a permission error. This is by design. When IDP Groups Mapping is not enabled, the proxy uses a pre-configured service account token with read-only access to Argo CD. No user identity or group information is forwarded. To perform write operations from within the Kargo dashboard, enable [IDP Groups Mapping](#enabling-write-access-idp-groups-mapping). ## Enabling write access: IDP Groups Mapping The IDP Groups Mapping setting enables write operations in the embedded Argo CD UI for users whose IDP group memberships grant them the necessary permissions in Argo CD RBAC. When IDP Groups Mapping is enabled, the user's IDP group memberships are passed through to Argo CD on every request. Argo CD then evaluates those groups against its own RBAC policies to determine what the user is allowed to do. **Argo CD RBAC is the single source of truth for write permissions.** Enabling this setting does not grant any user blanket write access — it makes group-based authorization flow through to Argo CD, where your existing RBAC rules take effect. :::caution IDP Groups Mapping requires that the group names from Kargo's identity provider **match the groups referenced in Argo CD's RBAC policies**. If the group names differ between the two systems, Argo CD may not recognize the user's groups, leading to unexpected permission denials. ::: ### Enabling IDP Groups Mapping In the Akuity Platform, navigate to Kargo → _your instance_ → Settings. 1. In the left panel, select the Argo CD UI tab. ![Kargo Settings — Argo CD UI tab](../../../static/img/argo_in_kargo_settings_in_akp.png) 1. Enable the IDP Groups Mapping toggle. ![IDP Groups Mapping toggle](../../../static/img/argo_in_kargo_toggle_in_akp.png) 1. Click Save. Once saved, any user whose IDP groups are mapped to a write-enabled role in Argo CD RBAC will be able to perform sync, delete, and other write operations from the Kargo dashboard. :::note Users whose IDP groups are not granted write access in Argo CD RBAC will continue to see the read-only view even after this setting is enabled. The setting does not bypass Argo CD RBAC — it makes group-based authorization possible. ::: ## Frequently asked questions **Does enabling IDP Groups Mapping give all users write access?** No. Enabling the setting makes group-based authorization possible, but actual permissions are determined by Argo CD RBAC. A user must belong to an IDP group that is explicitly granted write access in Argo CD's RBAC configuration. **Why do I see a permission error when I try to sync?** Either IDP Groups Mapping is not enabled, or your IDP groups are not mapped to a write-enabled role in Argo CD RBAC. Check the setting in Kargo → _your instance_ → Settings → Argo CD UI, and verify your Argo CD RBAC configuration. **Is the embedded view fully equivalent to the Argo CD UI?** No. The embedded view covers the most commonly used features: application details, resource trees, sync status, and history. It is not fully feature-equivalent to the standalone Argo CD UI. For operations not available in the embedded view, click Open in Argo CD UI to go directly to the full Argo CD dashboard. **Do I need to configure anything in Argo CD to use this feature?** No additional Argo CD configuration is required for read-only access. For write access via IDP Groups Mapping, ensure your Argo CD RBAC policies include the relevant IDP group names and grant them the necessary permissions. **Will this work if I use self-hosted Kargo or self-hosted Argo CD?** No. The embedded Argo CD UI is available only when both Kargo and Argo CD are managed by the Akuity Platform. --- ## Enable Akuity Intelligence The Akuity Intelligence feature is enabled in the Argo CD instances settings. Once enabled, the functionality is available to the end users through the Argo CD and Kargo UI extensions. ## Enable Akuity Intelligence at the Argo CD instance level The Akuity Platform administrator can enable the feature in Settings → Intelligence: ![Enable Intelligence](/img/intelligence_01.png) By default, the functionality is enabled for all Kubernetes clusters managed by Argo CD instances. Administrators can choose to enable the feature only for a subset of clusters. ## Manage Argo CD extension The Akuity Intelligence functionality is available to end users in the Argo CD UI through an extension, which is enabled by default. Administrators can manage the extension in the Argo CD instance settings under Settings → Extensions, where they can install or uninstall it as needed: ![Argo CD extension](/img/intelligence_02.png) By default, the extension is available for all users. Optionally, administrators can specify which subset of users has access to the functionality in the extension settings. To specify users click the gear button and provide Argo CD user names or OIDC groups: ![Extension access](/img/intelligence_03.png) After that, Argo CD user will see Intelligence (Beta) on the sidebar and floating button and on the Akuity-managed Argo CD instance UI: ![Argo CD UI](/img/intelligence_04.png) ## Manage Kargo extension The Akuity Intelligence functionality is available to end users in the Kargo UI through an extension, which is enabled by default. Administrators can manage the extension in the Kargo instance settings under Settings → Extensions, where they can install or uninstall it as needed: ![Kargo extension](/img/intelligence_05.png) By default extension is available for all users. Optionally, administrators can specify which subset of users has access to the functionality in the extension settings. To specify users click the gear button and provide Kargo user names or OIDC groups: ![Kargo access](/img/intelligence_06.png) After that, user will see Intelligence on the sidebar and floating button, and on the Kargo instance UI as well: ![Kargo UI](/img/intelligence_07.png) ## Akuity Intelligence Usage Administrators can monitor Akuity Intelligence usage in Intelligence, click the Usage tab, which provides a breakdown of usage grouped by the Argo CD and Kargo instances within the current organization. ![Akuity Intelligence Usage](/img/intelligence_59.png) The usage metrics includes **Instance**, **Cluster**, **API Resource**, **Object**, **Node**, **Pod**, **Container** and **AI Token**. --- ## Bring Your Own Models / Keys Akuity Intelligence introduces the Bring Your Own Key (BYOK) capability, enabling customers to integrate their own API keys or preferred model providers. Any provider offering an OpenAI-compatible or Anthropic-compatible API is supported, including public cloud model services as well as self-hosted open-source models. ## Benefits of BYOK - **Flexible cost management:** Customers can use their own API keys to control AI usage and associated costs, without relying on Akuity-based billing. - **Enhanced data privacy and compliance:** Organizations with strict privacy or regulatory requirements can route all AI traffic to private or on-premises deployments. - **Freedom to use the latest models:** Customers can access any newly released or alternative models—beyond Akuity’s default catalog—simply by adding their provider keys. :::warning If you use a custom model instead of an Akuity fine-tuned models, the model's performance and capabilities may not be optimal. ::: ## Supported Model Providers Akuity Intelligence currently supports the following providers: - OpenAI - Anthropic - OpenRouter - Bedrock - Gemini - Google AI Studio - Any self-hosted model exposing an OpenAI-compatible or Anthropic-compatible API ## Setup ### Getting Started with BYOK To start using the BYOK (Bring Your Own Key) feature: 1. Navigate to Intelligence, click Settings in the top right corner, from the left-hand menu, select the Models tab, click Add. ![Add and Change Model](/img/intelligence_53.png) 2. Select Provider, currently we support OpenAI, Anthropic and OpenRouter. If you are using self-hosted model with OpenAI/Anthropic compatible API, choose OpenAI/Anthropic provider. 3. The **Prefix ID** helps distinguish models with the same name from different providers (for example, both OpenAI and OpenRouter may offer a model named GPT-5.1). 4. If you are using self-hosted model, change the **API Base URL** to your model endpoint. 5. Select models from the model dropdown list. By default, only the latest **GPT** and **Claude** series models are listed. If the model you want is not in the list, you can manually enter the model ID. ![Add Custom Model](/img/intelligence_54.png) Save your custom model configuration. You can switch the Akuity Intelligence model to your newly configured model using the model dropdown at the top. --- ## Overview Dashboard The Overview dashboard is the central landing page for understanding the health and status of your entire Kubernetes environment. It provides a high-level, at-a-glance summary of all clusters connected to your Argo CD instance, including resources that are not managed by Argo CD. The dashboard consolidates key metrics into two main categories: resource inventory and incident insights: * **Resource Inventory** * **Clusters and Nodes**: The total number of connected Kubernetes clusters and the nodes running within them. * **API Resources and Objects**: A total number of all API resources and Kubernetes objects in all clusters connected to your Argo CD instance. * **Pods, Containers and Images**: A summary of the workloads currently running. * **Incident and Issue Insights** * **Incidents**: The number of active incidents that Intelligence is currently tracking or resolving. * **CVE Images**: A count of running container images with known security vulnerabilities (CVEs). * **Stuck-in-Deletion Resources**: Resources that are stuck in a terminating state and may require manual intervention. * **Deprecated APIs**: A warning for any Kubernetes APIs in use that are deprecated and will be removed in a future version. ![Overview](/img/intelligence_08.png) Each card on the overview dashboard is clickable, and will redirect you to a separate dashboard with deeper insight. --- ## Explorer Dashboard This is a multi-cluster Kubernetes dashboard that allows you to browse through the resources of all clusters connected to the Akuity Platform, even those not managed by Argo CD, without the restriction of viewing one application at a time. ![Explorer](/img/intelligence_09.png) The Cluster, Namespace, Kind dropdowns, as well as the Spotlight Search button on the right top allow you to quickly find specific resources based on your needs. When you find the resource that you are looking for, click the entry to gather more information: ![Resource details](/img/intelligence_10.png) Each tab provides specific insights into the resource's behavior and status: * **Event Timeline:** Provides a time series view of events related to the selected resource, helping to understand its lifecycle and correlation with other events. * **Manifest:** Displays the YAML definition of the resource, allowing inspection of its configuration. * **Logs:** Aggregates live logs from all containers within the resource, providing real-time insights into application behavior. * **Events:** Lists all Kubernetes events associated with the resource (e.g., creation, updates, errors), offering a detailed audit trail. * **Audit Logs:** Provides a record of all actions performed on the resource, including who initiated the action and when, crucial for security and compliance. ## Tree View The Tree View enables you to see all of the services and how they relate to each other. It provides a real-time dependency graph of your Kubernetes resources and visualizes the complex relationships between them. It displays each object—such as a Deployment, Service, or Pod—as an interactive card, with lines connecting them to show how they are managed and related. This allows you to instantly understand your application's architecture and trace dependencies. You can easily navigate your environment using the filters at the top to narrow the view by cluster, namespace, resource kind, or health status. ![Tree View](/img/intelligence_11.png) ## Event Timeline View Click the Namespace button in the top-right corner to open the detailed timeline view. The Namespace Event Timeline provides a powerful, correlated view of all activities and health changes for the resources within a specific namespace. This feature is designed to simplify root cause analysis by visualizing the sequence of events over time. ![Timeline](/img/intelligence_12.png) The timeline consolidates and displays a wide range of events in a single, chronological view, including: * **Resource Health Changes**: Tracks the health status of individual resources like Deployments, showing transitions between states such as Healthy, Progressing, and Degraded. * **Spec Changes**: Pinpoints the exact moment a resource's specification was modified. * **Audit Logs**: Displays audit trail events related to resource changes. * **Sync Operations**: Shows when Argo CD sync operations were initiated. * **Kargo Promotions**: Marks when promotions between Kargo stages occurred. * **Node Events**: Correlates cluster-level node events with application behavior. --- ## Deprecated APIs Dashboard The Deprecated APIs Dashboard provides a list of deprecated Kubernetes APIs and important details: * **API Version & Kind**: The full name of the deprecated API and its resource kind. * **Kubernetes Version**: The current version of the cluster where the API was found. * **Deprecated In**: The Kubernetes version in which the API was officially marked as deprecated. * **Unavailable In**: The future Kubernetes version in which the API will no longer be available. * **Migrate To**: The recommended new API version that you should migrate your resources to. * **Resource Count**: The number of live resources currently using this deprecated API. A count greater than zero indicates that action is required. ![Deprecated APIs](/img/intelligence_13.png) This dashboard provides the insights to let teams know where and how to prioritize the proper migration. There are 4 different severities: * **Critical**: already deprecated in current kubernetes version and resource count > 0 * **High**: already deprecated in current kubernetes version and resource count is 0 * **Medium**: will be deprecated in next kubernetes minor version and resource count > 0 * **Info**: will be deprecated in next kubernetes minor version and resource count is 0 ## Understanding the Resource Count The **Resource Count** is based on the API version Kubernetes uses to _store_ each resource in etcd, not the `apiVersion` written in your Git manifests or displayed in Argo CD. These can differ. Kubernetes APIs, including those defined by [Custom Resource Definitions (CRDs)](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/), can be served under several versions at the same time, but every object is persisted under a single _storage version_, usually the newest, non-deprecated one. When you apply a resource using a deprecated `apiVersion`, Kubernetes converts it to the storage version before saving it. Argo CD, by contrast, treats the `apiVersion` in your Git manifest as the source of truth and displays that. Because of this, a resource can show a deprecated `apiVersion` in Argo CD while still contributing **zero** to the Resource Count: the live object is actually stored under a newer version. This is expected behavior. A Resource Count of zero means no live objects are stored under the deprecated API, so no migration is required for it. :::note To check the storage version of a CRD, run: ```shell kubectl get crd -o jsonpath='{.spec.versions[?(@.storage==true)].name}' ``` If the storage version is already a non-deprecated version, a deprecated `apiVersion` in your manifests is harmless. Kubernetes never persists an object under it. ::: --- ## Stuck-in-Deletion Resources Dashboard The Stuck-in-Deletion Dashboard provides visibility into Kubernetes resources across multiple clusters that are unable to complete the deletion process. It aggregates and surfaces resources stuck in the terminating state, helping platform and operations teams quickly identify problem areas that may block workloads, consume cluster resources, or cause cascading issues. ![Stuck-in-Deletion](/img/intelligence_14.png) You can view more details about why it is stuck in deletion by clicking the entry, the finalizers will be highlighted: ![Finalizers](/img/intelligence_15.png) --- ## Containers Dashboard ![Containers](/img/intelligence_16.png) The Containers Dashboard displays a comprehensive overview of containers running across your connected Kubernetes clusters. It provides insights into their status, resource utilization, and other critical metrics, enabling you to monitor and manage your containerized applications effectively. You can drill down into individual containers to view more detailed information and identify potential issues: ![Container details](/img/intelligence_17.png) --- ## Images Dashboard The Images Dashboard provides a detailed view of container images across your connected Kubernetes clusters. It offers insights into image usage, vulnerabilities, and other critical information, helping you manage and secure your container images effectively. You can also explore individual images for more in-depth analysis and identify potential security risks or optimization opportunities. ![Images](/img/intelligence_18.png) ## CVE Scanning CVE Scanning within Akuity Intelligence is optional and it is disabled by default. To enable CVE scanning, navigate to Settings → Intelligence in your Argo CD instance. From there, locate the CVE Scanning option and toggle it on or off as needed: ![Enable CVE Scanning](/img/intelligence_19.png) Once CVE scanning is enabled, you can view the results on the Images dashboard. This dashboard provides a detailed view of container images across your connected Kubernetes clusters, including identified vulnerabilities. You can explore individual images for more in-depth analysis of security risks. ![CVE Results](/img/intelligence_20.png) ### CVE Found in Application Detail You can also access CVE scanning results directly from the Application Detail page. When CVE scanning is enabled, the Akuity Intelligence section in the top-right corner of the Application Detail page displays a CVEs Found button, showing the total number of CVEs detected across all images in the application. Clicking this button navigates you to the Images Dashboard, filtered by the selected application, for a detailed view of the vulnerabilities. ![CVE Found in Application Detail](/img/intelligence_58.png) --- ## Infrastructure Dashboard The Infrastructure Dashboard provides a comprehensive overview of your Kubernetes cluster resources, offering multiple views to analyze utilization and capacity. ## Node View This view provides a high-level look at the nodes in your cluster, visualizing their resource utilization (e.g., CPU Utilization) to help you quickly assess node health. Each node is color-coded to represent its current consumption level: * **Green**: Indicates low resource utilization. * **Yellow/Orange**: Represents moderate resource utilization. * **Red**: Signals high resource utilization, indicating the node is under heavy load and may require investigation. ![Nodes](/img/intelligence_21.png) Clicking on a cluster provides a comprehensive overview of its status, displaying: * **CPU and Memory:** Current usage and requests relative to allocatable capacity. * **Pods:** Total and running pod counts. * **Nodes:** A list of all nodes, including their current status and age. ![Cluster overview](/img/intelligence_22.png) ## Pod View The Pod view presents a visual grid of all pods, enabling you to: * **Visualize Pods:** Pods appear as hexagonal tiles, with colors indicating resource usage. * **View Details:** Hover over a pod to see its name, namespace, and CPU/memory consumption. * **Filter and Search:** Utilize dropdowns to filter by metrics (e.g., CPU Usage) or search for specific pods. ![Pods](/img/intelligence_23.png) ## Namespace View The Namespace view offers two ways to analyze resource consumption per namespace: * **Treemap:** This visualizes namespaces as rectangles, with their size corresponding to their resource usage (e.g., Memory Usage). ![Namespaces treemap](/img/intelligence_24.png) * **Bar Chart:** This displays metrics such as Memory Usage/Request percentages for each namespace. ![Namespaces bar chart](/img/intelligence_25.png) ## Argo CD Applications View The Argo CD Applications view provides a comprehensive overview of all Argo CD applications in your cluster, enabling you to view the applications and their status. * **Visialize Health Status:** Quickly view the health status of all applications and easily identify degraded or missing applications. * **Visualize Sync Status:** Quickly view the sync status of all applications and easily identify applications that are out of sync. ![Argo CD Applications](/img/intelligence_26.png) --- ## Insights Dashboards --- ## Deployment Advisor Users can initiate free-flow conversations with the Deployment Advisor to triage issues by selecting a Kargo project, Argo CD applications, or Kubernetes namespaces as contexts. This allows for direct interaction with the Deployment Advisor to troubleshoot and gain insights into specific resources. ![Context selection](/img/intelligence_26.png) The Deployment Advisor will attempt to answer user questions by calling necessary functions such as getting the application tree, retrieving logs, or searching up-to-date documentation, etc. ![Agent reply](/img/intelligence_27.png) ## Tasks Akuity Agent can perform periodic, automated tasks on behalf of DevOps engineers. **Tasks** are the first‑class way to define, run, and track those automations inside the platform. ### Overview A **Task** represents a recurring automation executed by the Akuity Agent. It allows you to define a job description in natural language and set a schedule for it to run. Key features: - **Natural Language Schedule**: Define schedules using plain English (e.g., "daily at 2am", "every Monday at 9am") or standard cron expressions like "0 2 * * *". - **Automated Execution**: The agent automatically runs the task at the specified times. - **History & Reporting**: Every execution is recorded, providing a clear history of what was checked and any actions taken. ### Create a Task You can create a Task directly from the Akuity Platform UI. 1. Navigate to the **Intelligence** section. 2. Select **Tasks**. 3. Click **Create**. 4. Enter the required fields: - **Title**: The name of the task. - **Schedule**: Define the schedule using natural language or cron expressions. - **Status**: Set the status to **Active** or **Suspended**. - **Contexts**: Select the contexts that the task will focus on. - **Description**: Provide the task description. > **Note:** Being specific in your task description helps the agent perform the task more accurately. ![Create Task](/img/intelligence_50.png) ### Manage Tasks Once created, you can view and manage all your tasks from the Tasks page. - **Execution**: See the schedule, last execution time, next execution time, and total runs. - **Latest Report**: View a summary of the most recent execution. - **History**: Click on a timestamp to view its detailed reports from previous runs. You can edit or delete existing tasks as needed. Also, you can open the task in the normal conversation to see more details. ![Task Detail](/img/intelligence_51.png) If [Slack integration](#slack-integration) is configured, you will also receive task execution reports directly in your Slack channel. ![Task Report in Slack](/img/intelligence_52.png) ### Example Tasks We have established some example tasks in this [GitHub repository](https://github.com/akuity/akuity-intelligence-examples). You may directly import them into your own instance via the **Import** button. > **Note:** After importing, the task will not start by default. You need to set the status to **Active** and add the corresponding **Contexts**. ![Example Tasks](/img/intelligence_55.png) ## Slack Integration You can pipe Deployment Advisor updates into Slack by sharing the same Slack integration setup used by the On-Call Agent. Follow the configuration steps in [Slack Integration](20-on-call-agent.md#slack-integration) to connect Argo CD notifications with Slack before sharing conversations from the Deployment Advisor. Additionally, [task executions](#manage-tasks) can also send messages to Slack. --- ## On-Call Agent The On-Call Agent automates troubleshooting and remediation for your degraded Argo CD applications and Kubernetes namespaces by executing predefined runbooks. An incident is an investigation of a namespace or app in a degraded state. Incidents are either kicked off automatically by the On-Call Agent upon a detected degraded state or manually when a user converts a conversation to an incident. Once the incident is created, the On-Call Agent will begin troubleshooting and triage. An incident follows the same pattern as a conversation with the Deployment Advisor with a couple of key differences: * There is a status associated with the incidents, resolved / active * Incidents are associated with a particular resource (E.g., an Argo CD application or a Kubernetes Namespace) Incidents are either kicked off automatically by the On-Call Agent upon a detected degraded state or manually when a user converts a conversation to an incident. ## Enable Incident Auto-Creation From the Intelligence settings page, you can configure the conditions under which an incident is automatically created when your Argo CD applications or Kubernetes resources enter a degraded state. ![Auto-creation triggers](/img/intelligence_28.png) Resource Degradation Triggers allow you to automatically create incidents when your Argo CD applications or Kubernetes resources enter a degraded state. ![New trigger](/img/intelligence_29.png) To create a trigger: * Click Add New under the Resource Degradation Triggers section. * Fill in the following fields in the "New Trigger" dialog: * **Argo CD Applications**: Select which specific Argo CD applications to monitor. * **K8S Namespaces**: Select which Kubernetes namespaces to monitor. * **Clusters**: Choose the cluster(s) this trigger will apply to. * **Trigger After**: Specify a delay (e.g., 5m, 15m, 1h30m) before creating an incident. This prevents alerts for brief, transient issues. ## Webhook triggers Webhook triggers let you create incidents from alerts sent by external monitoring systems such as Prometheus Alertmanager, Grafana, Datadog, or any tool that can send an HTTP POST request. When the Akuity Platform receives a webhook, it extracts incident metadata from the JSON payload using JSONPath expressions you define and creates an incident for the On-Call Agent to investigate. ### Configure a webhook trigger From the Intelligence settings page, under the Webhook Triggers section: ![Webhook triggers](/img/intelligence_57.png) 1. Click Add New. 1. In the New Webhook Config dialog, fill in the following fields: * **Name** (required): A unique identifier for this webhook configuration (e.g., `alert-manager`). * **Description**: A JSONPath expression that maps to the incident summary from the webhook payload (e.g., `{.body.alerts[0].annotations.description}`). * **Cluster**: A JSONPath expression that maps to the cluster name. This can reference query parameters as well (e.g., `{.query.clusterName}`). * **K8s Namespace**: A JSONPath expression that maps to the Kubernetes namespace (e.g., `{.body.alerts[0].labels.namespace}`). * **Argo CD Application Name**: A JSONPath expression that maps to the Argo CD application name. * **Argo CD Application Namespace**: A JSONPath expression that maps to the Argo CD application namespace. If an application name is provided but the namespace is omitted, it defaults to `argocd`. ![Webhook config](/img/intelligence_30.png) 1. Click OK to save the configuration. 1. Click Save in the top-right corner to apply the changes. After saving, the dashboard displays a generated webhook URL next to each configuration. Copy this URL and configure it in your alerting system as the target endpoint. ### Webhook URL format Each webhook trigger produces a URL in the following format: ``` https:///api/v1/orgs//ai/incidents?webhook_name=&instance_id= ``` * `organization_id`: Your Akuity organization ID. * `webhook_name`: The name you assigned to the webhook configuration. * `instance_id`: The Argo CD instance ID associated with this trigger. The endpoint accepts a `POST` request. The request body must be a valid JSON payload. The Akuity Platform evaluates the JSONPath expressions you configured against the payload to extract incident metadata. ### Authentication :::warning All webhook requests must be authenticated. Unauthenticated requests will be rejected. ::: The webhook endpoint uses HTTP Basic Authentication. Set the username to your **API Key ID** and the password to your **API Key Secret**. The API key must have the **Organization Owner** role, or a [custom role](../../02-akuity-portal/02-organizations/40-custom-roles.md) with **Akuity Intelligence** create permission. To create an API key, see [API Keys](../../02-akuity-portal/02-organizations/20-api-keys.mdx). ### JSONPath expressions Field mappings use Kubernetes-style JSONPath syntax. The expressions are evaluated against a root object that contains two keys: * `body`: The parsed JSON body of the incoming webhook request. * `query`: A map of query parameters from the request URL. For example, if Prometheus Alertmanager sends a payload like: ```json { "alerts": [ { "labels": { "namespace": "production", "alertname": "HighMemoryUsage" }, "annotations": { "description": "Pod memory usage exceeds 90%" } } ] } ``` You could use the following JSONPath expressions: | Field | JSONPath expression | | ------------- | ------------------------------------------- | | Description | `{.body.alerts[0].annotations.description}` | | K8s Namespace | `{.body.alerts[0].labels.namespace}` | | Cluster | `{.query.clusterName}` | In this example, the cluster name is passed as a query parameter. Your alerting system would send the webhook to: ``` https:///api/v1/orgs//ai/incidents?webhook_name=alert-manager&instance_id=&clusterName=my-cluster ``` :::tip If a JSONPath expression matches multiple values, they are joined with commas. If a field's JSONPath is left empty, the corresponding incident field is left blank. ::: ### Example: Prometheus Alertmanager To integrate with Prometheus Alertmanager, add a webhook receiver to your Alertmanager configuration: ```yaml receivers: - name: akuity-intelligence webhook_configs: - url: "https:///api/v1/orgs//ai/incidents?webhook_name=alert-manager&instance_id=&clusterName=my-cluster" send_resolved: true http_config: basic_auth: username: password: ``` Then configure the corresponding webhook trigger in the Akuity Platform with the following field mappings: | Field | JSONPath expression | | ------------------------ | ------------------------------------------- | | Description | `{.body.alerts[0].annotations.description}` | | K8s Namespace | `{.body.alerts[0].labels.namespace}` | | Cluster | `{.query.clusterName}` | | Argo CD Application Name | `{.body.alerts[0].labels.app}` | When Alertmanager fires an alert, the Akuity Platform creates an incident and the On-Call Agent begins troubleshooting using any applicable runbooks. ## Create Runbooks Runbooks, at a high level, are the instruction sets that the On-Call Agent uses when responding to an active incident or scenario. These runbooks are written and stored in markdown formatting making them easy to read between both humans and Intelligence. There is no preset schema or format that you need to follow for a runbook, the On-Call Agent will interpret whatever you have written and assess it for actions when a corresponding incident occurs. For example, you may have an incident in which an application has hit the memory limit and entered into an out of memory (OOM) state. Based on the runbooks you have in the environment, the On-Call Agent can perform the following: * Identify what runbook is most applicable to the caused incident * Report status and custom pieces to a Slack channel * Suggest a change and wait for approval from a user Example: ```markdown ## General - First, do the initial triage and collect the basic information to understand the incident. - Next, send a slack notification with the link to the conversation to channel “on-call” with basic detail. - Next, work on the incident according to the runbook. Don't take any action automatically, ask for approval. - If the app is stable, check 30 seconds later again, then you can close the incident automatically. Please do slack all the details in concise messages. - If you stack send a slack message again and mention that you need help. - Please ensure you send slack message with the link to the conversation, so engineer can work with you together if needed. ## Out of memory **Symptoms**: Pod unexpectedly dies with `OOMKilled` status. **Root cause**: The pod is consuming more memory than the available memory. **Solution**: * Temporary increase the memory limit of the pod automatically * Increase the memory limit with the 50 Mb increment until the pod is stable. ``` Users can manage their runbooks under the Runbooks tab of Incidents dashboard. ![Runbooks](/img/intelligence_31.png) ## GitOps-Managed Runbooks In addition to creating runbooks manually in the UI, you can connect Git repositories and let Akuity pull runbooks directly from your version-controlled markdown files. This lets you manage runbooks with the same Git workflows you use for everything else — pull requests, reviews, and history included. ### Connect a Git Repository 1. Navigate to Intelligence → Incidents → Runbooks. 2. Click the Import dropdown and select Connect Git repo. 3. In the Connect Git Repositories dialog, add one or more repository URLs. - **Repository URL** (required): the HTTPS URL of your Git repository. - **Revision** (optional): a branch, tag, or commit SHA. Defaults to the repository's default branch. - **Path glob** (optional): a glob pattern to filter which files are fetched. Defaults to `**/*.md`, which picks up all markdown files. 4. Click Save. Akuity will begin syncing runbooks from the repository periodically. :::tip The [akuity-intelligence-examples](https://github.com/akuity/akuity-intelligence-examples) repository contains a curated set of ready-to-use runbooks. Click **Add** next to the suggestion in the dialog to connect it instantly. ::: ### Runbook File Format Any `*.md` file in the connected repository is a candidate runbook. Add a YAML front matter block at the top of the file to configure its name, targeting, and notifications. Files without front matter are still imported — they just won't be auto-triggered by the On-Call Agent. ```markdown --- name: OOM Runbook applied_to.clusters: production, staging applied_to.argocd_applications: my-app-* applied_to.k8s_namespaces: default applied_to.degraded_for: 5m slack_channel_names: on-call, alerts --- ## Out of Memory **Symptoms**: Pod unexpectedly dies with `OOMKilled` status. **Solution**: Temporarily increase the memory limit by 50 MB increments until the pod stabilizes. Notify the on-call channel with a link to this incident. ``` Supported front matter fields: | Field | Description | |---|---| | `name` | Display name for the runbook. Defaults to the file path. | | `applied_to.clusters` | Comma-separated cluster name patterns. Use `*` to match all clusters. | | `applied_to.argocd_applications` | Comma-separated Argo CD application name patterns. Supports wildcards, e.g. `my-app-*`. | | `applied_to.k8s_namespaces` | Comma-separated Kubernetes namespace patterns. Supports wildcards. | | `applied_to.degraded_for` | Minimum duration a resource must be degraded before this runbook triggers, e.g. `5m`, `1h`. | | `slack_channel_names` | Comma-separated Slack channel names to notify when this runbook runs. | ### Configuring Targeting for GitOps Runbooks GitOps runbooks pick up their `applied_to` targeting from the YAML front matter inside each file. If you need to configure or override targeting without editing the source file — for example, when the repository is owned by another team, or when you want environment-specific targeting — you can set overrides directly in the Akuity UI or via Terraform. Overrides are stored per-runbook-name inside the repository configuration and take precedence over any `applied_to` values in the file's front matter. #### From the UI 1. In the Runbooks sidebar, select a runbook that was imported from a Git repository. 2. In the detail pane, click Edit Targeting. 3. Configure the **Argo CD Applications**, **K8S Namespaces**, and **Clusters** fields exactly as you would for a manual runbook. 4. Click Save. The override is stored immediately; the On-Call Agent will use it on the next incident without waiting for a repository sync. :::note The runbook content itself remains read-only — only the targeting is overridden. To change the content, edit the source file in your repository. ::: #### Via Terraform Use the `applied_for` map inside a `runbook_repos` block. Each key is a runbook name (derived from the file name after stripping the extension); the value is a target selector: ```hcl resource "akp_instance" "example" { argocd = { spec = { instance_spec = { kube_vision_config = { ai_config = { runbook_repos = [ { repo_url = "https://github.com/my-org/runbooks" revision = "main" applied_for = { "oom-kill" = { argocd_applications = ["guestbook-*"] clusters = ["prod-cluster"] } "restart-pod" = { k8s_namespaces = ["default", "staging"] clusters = ["*"] } } } ] } } } } } } ``` ### Sync Status Each connected repository shows a status indicator in the runbooks sidebar: - **Green** — the repository was synced successfully. Hover to see the last sync time. - **Yellow** — the last sync attempt failed. Hover to see the error message. - **Spinning** — the repository is waiting for its first sync. Click a repository row to open the Connect Git Repositories dialog and manage its configuration. ### Permissions For private repositories, make sure the Argo CD instance has credentials configured for the repository URL under Settings → Repositories. Akuity uses the same repository credentials as Argo CD when fetching runbook files. GitOps-managed runbook **content** is read-only in the UI — edit it in your repository and it will be updated on the next sync. Targeting (`applied_to`) can be overridden per-runbook directly from the UI without touching the source file. See [Configuring Targeting for GitOps Runbooks](#configuring-targeting-for-gitops-runbooks) below. ## Apply Runbooks to your Resources After creating a runbook, you must apply it to your Argo CD applications or Kubernetes namespaces. When a linked resource becomes degraded, the On-Call Agent will automatically execute the steps defined in the runbook to resolve the incident. There are two ways to apply a runbook to your Argo CD applications or Kubernetes namespaces: * From the Runbook Settings UI. You can directly configure which resources a runbook applies to from the runbook editor. * Navigate to Intelligence (Beta) in the left-hand sidebar. * Select the Runbooks tab. * Click + Create to make a new runbook, or select an existing runbook and click Edit. * In the Applied To section, specify the Argo CD Apps, K8S Namespaces, or Clusters that this runbook should monitor. * In the example, the runbook named oom is applied to the Argo CD Application `guestbook-prod-oom`. * Using Kubernetes Annotations. You can also apply a runbook by adding an annotation directly to the manifest of your Argo CD Application or Kubernetes Namespace. * Add the annotation `akuity.io/runbooks: ""` to the resource's metadata. * For the example shown, you would add the following annotation to the guestbook-prod-oom Application resource: `akuity.io/runbooks: "oom"` ## Example Runbooks We have established some example runbooks in the [akuity-intelligence-examples](https://github.com/akuity/akuity-intelligence-examples) GitHub repository. There are two ways to use them: - **One-time import**: Click the Import dropdown and select Import examples to copy the runbooks into your instance. You can then edit them freely in the UI. - **GitOps sync**: Click the Import dropdown and select Connect Git repo, then add `https://github.com/akuity/akuity-intelligence-examples`. Runbooks will stay in sync with the repository automatically. ![Example Runbooks](/img/intelligence_56.png) > **Note:** After importing, the runbook will not be enabled by default. You need to add the corresponding **Applied To** configuration to enable the runbook. ## Managing Incidents When an Argo CD application or Kubernetes namespace becomes degraded, the On-Call Agent will automatically create an incident. You can view and manage these incidents from the Incidents dashboard. The Incidents tab will display a list of all incidents. You can filter this list by Status (e.g., Unresolved, All), Application, or Namespace. ![Incident details](/img/intelligence_32.png) Click on an incident from the list to view its details. This view provides a live, step-by-step account of the troubleshooting process: * **Summary**: A high-level overview of the issue, including the affected application and the runbook being used. * **Root Cause**: An analysis of the likely cause of the incident (e.g., an OOMKilled event due to memory limits). * **Live Troubleshooting Log**: A timeline showing every action taken by the intelligence agent, from initial detection ("Incident Occurred") to diagnostic steps like fetching the application tree and inspecting Kubernetes resources. The On-Call Agent will attempt to resolve the incident automatically using the applied runbook. * If the incident is successfully resolved, its status will be updated to Resolved. * If the issue persists, the incident will remain Unresolved. You can then take manual action: * **Mark as Resolved**: If you have fixed the issue outside of the system, you can manually close the incident. * **Open in Akuity Intelligence**: Click this button to open the incident in the chat interface. Here, you can work directly with the On-Call Agent, provide more instructions, or ask it to "resolve it" to continue the troubleshooting process interactively. ## Slack Integration Akuity Intelligence can notify Slack about incidents and, if you enable the full Slack Integration, keep conversations in sync. Use the configuration level that matches what you need: * Send incident updates to Slack using Argo CD notifications, this is **single directional** conversation sync. it sends alerts to Slack from Akuity Intelligence. * Add **bi-directional** conversation sync, Share to Slack, and thread-first workflows. This layer builds on the alerting setup and requires [additional Slack app permissions](#additional-setup-for-slack-integration). ### Configure the Slack Service ![Slack service](/img/intelligence_33.png) Both experiences rely on an Argo CD Slack service. Create or update it under Settings → Notifications → Services: 1. Click Add New → Slack (or edit an existing service). 2. Provide a **Name** (e.g., `slack-main`). 3. Enter your Slack **Bot Token** (`xoxb-…`). This is required for incident notifications. 4. (Slack Integration only) Enter your **App-Level Token** (`xapp-…`) so Socket Mode can power live conversation sync. 5. Optionally set a posting **Username** and **Icon**. 6. Save the service. > If you rotate either token later, update the Slack service to avoid delivery failures. ### Link Slack to Akuity Intelligence ![Link Slack](/img/intelligence_34.png) After the Slack service exists, connect it to Intelligence so incident updates flow to Slack: * Click on the Integrations tab. * In the Notifications section, locate the Slack option. * Click the dropdown menu and select the Slack service you configured in the previous step. * Click Save in the top-right corner to apply the changes. With this in place, the On-Call Agent posts new and ongoing incident activity to the channels configured for that Slack service. ### Additional Setup for Slack Integration If you plan to collaborate directly from Slack threads, configure your Slack app with the permissions and subscriptions below. These steps unlock Share to Slack, bi-directional chat, and conversation sync without changing how the On-Call Agent posts incident alerts. #### Generate an App-Level Token App-level tokens let Akuity connect to Slack platform features such as Socket Mode. 1. Navigate to Settings → Basic Information → App-Level Tokens. 2. Click Generate an app-level token. 3. Add the scopes: `connections:write`, `authorizations:read`, and `app_configurations:write`. #### Enable Socket Mode Socket Mode keeps Slack traffic behind WebSockets so you do not need to expose a public endpoint. 1. Open Settings → Socket Mode. 2. Turn on Connect using Socket Mode. #### Configure Event Subscriptions Event subscriptions allow Akuity to receive messages and mentions from the channels you monitor. 1. Go to Features → Event Subscriptions. 2. Enable Events. 3. Under Subscribe to Bot Events, add: `app_mention`, `message.channels`, `message.groups`, `message.im`, and `message.mpim`. #### Configure OAuth & Permissions Bot token scopes define what your Slack app can read and write when syncing conversations. 1. Open Features → OAuth & Permissions. 2. Under Scopes, add: `app_mentions:read`, `channels:history`, `channels:read`, `chat:write`, `groups:history`, `groups:read`, `im:history`, `mpim:history`, `users:read`, and `users:read.email`. #### Allowlist Slack Channels for Share to Slack 1. Return to the target Argo CD instance and open Settings → Intelligence → Integrations. 2. With your Slack service selected, find Slack Channels. 3. List the channels (without `#`) that should appear in the Share to Slack dialog. This acts as an allowlist. 4. Save the settings and invite the Slack app (bot user) to each listed channel so first posts succeed. ![Configure Slack Channels](/img/intelligence_45.png) When these optional steps are complete, the Slack Integration experience—thread sync, share-to-Slack workflows, and responding to incidents inside Slack—is available alongside the standard On-Call Agent notifications. ### Using Slack Integration Once configuration is complete, you can share conversations to Slack, collaborate inside threads, and review synced incidents without leaving Slack. #### Sharing Conversations to Slack After services and channels are configured, conversation owners can use the Share to Slack action in the AI Conversation UI: 1. Open a conversation and click Share to Slack. The modal lists the allowlisted channels you configured earlier. 2. Pick a destination. If the conversation is already shared, the modal shows the existing permalink and an Unshare option. 3. Confirm Share. The backend will make the conversation public if it was private, capture the title, generate a permalink, and post to the selected Slack channel with both pieces of context. Re-sharing to the same channel refreshes the thread and permalink. Unsharing clears the stored Slack metadata and returns the conversation to private visibility. #### Interacting in Slack * **Outbound (AKP → Slack)**: New messages in the AI conversation automatically post to the Slack thread. * **Inbound (Slack → AKP)**: When a human replies in the linked Slack thread or mentions the bot, the message syncs back to the AKP conversation. #### Automatic Incident Synchronization Akuity Intelligence can detect incidents (for example, degraded applications) and notify your team via Slack. The automation is driven by the runbooks attached to your resources. ##### Interacting with Incidents in Slack 1. **View Details**: Incident messages include a summary, ID (for example, `INC-123`), and a link back to the AKP console. 2. **Reply in Thread**: Collaborate directly in the Slack thread. 3. **AI Response**: The AI monitors the thread and responds to questions or commands (for example, “Get the logs for the test-service pod”). 4. **Two-Way Sync**: Every message in the Slack thread is mirrored in the incident conversation inside the AKP console. :::note The AI only posts to channels you explicitly allow in **Slack Channel Configuration**. Ensure your runbook references one of those channels. ::: #### Troubleshooting If Slack synchronization is not working as expected, verify the following: 1. **Permissions**: Confirm the Slack app includes the `channels:read`, `chat:write`, and `groups:read` scopes. 2. **Tokens**: In Settings → Notifications, ensure both Slack tokens are valid. 3. **Channel Membership**: Invite the Slack app (bot) to the target channel (`/invite @YourApp`). 4. **Socket Mode**: When using Socket Mode, confirm the app-level token is configured and Socket Mode is enabled. 5. **Runbook Instructions**: For incident sync, make sure your runbook tells the AI to post to Slack and names the correct channel. 6. **Service not listed**: Verify the Slack service you created under **Notifications** starts with `service.slack.` and save the Intelligence settings again. 7. **Share fails immediately**: The bot may lack access to the channel or tokens may be stale. Reinvite the bot, rotate the secrets, and click **Save** in Notifications. 8. **Slack replies do not sync**: Check platform logs for socket pool warnings. If the instance was unregistered, confirm both bot and app tokens resolve correctly from the secret. ## Interacting in Git Akuity Intelligence can read from and write to the Git repositories backing your Argo CD applications. It uses the Git credentials already configured for each application's repository in Argo CD — no additional credential setup is required. ### Reading Git Content You can ask the On-Call Agent to inspect repository content as part of troubleshooting or investigation. For example: * Retrieve the current value of a field in a manifest * Compare configuration between environments * Understand how manifests are structured or generated (plain YAML, Helm, Kustomize) ### Making Git Changes The On-Call Agent can make changes directly to the application repository. You can instruct it to commit to an existing branch or to create a new branch for review. **Committing directly to the main branch** is appropriate for immediate fixes where no review cycle is needed. For example: > *"Update the memory limit for the payment service to 512Mi and commit to main."* **Creating a new branch** keeps the change isolated and ready for a Pull Request. The agent will suggest a meaningful branch name, commit the change, and prepare a Pull Request with a descriptive title and summary. For example: > *"Create a PR that updates the image tag for the frontend deployment to v3.1.1."* Akuity Intelligence will scan the repository, determine how manifests are generated, locate the correct file, and apply the change — whether the application uses plain YAML, Helm values files, or Kustomize overlays. You do not need to specify which file to modify. ### Customizing Git Behavior You can define preferences for how the On-Call Agent interacts with Git by describing them in a runbook. For example, you can specify: * Whether changes should go to a new branch or directly to main * Preferred branch naming conventions * Required PR labels or reviewers * Whether to require human approval before pushing any change :::note Git write operations use the same repository credentials configured in Argo CD for the application. Ensure those credentials have write access to the repository if you intend to use the On-Call Agent for Git changes. ::: --- ## Promotion Advisor The Promotion Advisor helps you make safer and more informed deployment decisions by automatically analyzing the changes between application versions before a promotion. When you promote a `Freight` to a stage, the Promotion Advisor provides a detailed risk assessment, a summary of changes, and actionable recommendations. In the Kargo UI, initiate a promotion for one stage to a `Freight`. In the `Promote` dialog that appears, click on the AI Promotion Advisor tab. ![Promotion Advisor](/img/intelligence_36.png) By reviewing the Promotion Advisor's report, you can confidently decide whether to proceed with the promotion, armed with a clear understanding of the changes and their potential impact. ## Slack Integration The Promotion Advisor can also send notifications to Slack. For more details on configuring and using Slack integration, please refer to the [Slack Integration](./20-on-call-agent.md#slack-integration) section in the On-Call Agent documentation. --- ## Akuity Agents --- ## Akuity Intelligence Capabilities Akuity Intelligence can interact with Argo CD, Kargo, Kubernetes, and many third-party systems through tools. You can request the use of these tools in conversations with AI agents. These tools can also be used in runbooks. The following are all the tools available in Akuity Intelligence: * **** - Request or re-engage a multi-step execution plan for the current goal. Call this before other diagnostic or action tools when the current request will need three or more total tool calls across parallel or sequential execution, including audits, investigations, comparisons, and multi-part follow-ups. The runtime invokes the planner model and forces step-by-step execution. Do not use for direct answers, simple status checks, requests needing at most two tool calls, active scheduled tasks, or requests already executing inside an active plan step. * **Cancel task** - Cancel a previously scheduled follow-up task by its ID. Use this when new evidence makes the planned follow-up unnecessary. * **Create Git Repository Issue** - Creates a new issue in a Git repository. * **Create Git Repository Pull Request** - Create a pull request for a Git repository. * **Delete Kubernetes resource** - Deletes the specified Kubernetes resource. * **Disable Argo CD app auto-sync** - Disables the auto-sync feature of the Argo CD application. * **Edit Slack message** - Updates existing message with a new text. * **Get Argo CD app project** - Returns the JSON serialized project the Argo CD application belongs to. * **Get Argo CD application** - Retrieves Argo CD application information. * **Get Argo CD application events** - Returns the Argo CD K8S Events and Akuity Timeline Events for a given application. ## Parameters - since (string, ISO8601): Start of the time window. Use a narrow window (e.g. 1 hour around the incident) and paginate by advancing since/until to avoid overwhelming responses. - until (string, ISO8601): End of the time window. - severity (string enum): Minimum severity filter. Use "warning" or "critical" to skip informational node churn and focus on meaningful signals. Only use "info" when you need full detail for a narrow time window. - "info": returns all events (informational and above) - "warning": returns only warning and critical events — use this as the default for troubleshooting - "critical": returns only critical events - includes (string): Case-insensitive substring filter. When set, only K8S events whose Reason contains this string and timeline events whose message contains this string are returned. Use this to narrow results to events relevant to the incident (e.g. "OOMKill", "BackOff", "redis"). When the incident cause is known, always set this to avoid retrieving unrelated noise. ## Usage guidance Start with a 1-hour window around the incident using severity="warning". Paginate by sliding the since/until window if needed. Widen to severity="info" only when you need full context for a specific narrow window. When you know the incident cause, set includes to filter to relevant events only. * **Get Argo CD application tree** - Retrieves Argo CD application resource tree. * **Get Argo CD instance settings** - Returns the settings of the Argo CD instance. * **Get Argo CD instance version info** - Returns the version information of the Argo CD instance and configured tools. * **Get Argo CD managed resource diff** - Returns the difference between the current state and the desired state of a resource managed by an Argo CD application. * **Get Git Repository Issue Comments** - Returns a paginated list of comments for a specific issue in a Git repository. * **Get Git Repository Issue Details** - Returns details of a single issue in a Git repository. * **Get Kargo project** - Retrieves detailed information about a specific Kargo project including its metadata, status, and statistics about warehouses and stages. * **Get Kargo project tree** - Retrieves the hierarchical structure of Kargo resources in a project * **Get Kargo promotion** - Retrieves detailed information about a specific Kargo Promotion including its status, freight details, and progress information. * **Get Kargo stage** - Retrieves detailed information about a specific Kargo Stage including its spec with requested freight configuration and promotion rules. * **Get Kargo warehouse** - Retrieves detailed information about a specific Kargo Warehouse including its configuration for watching artifact sources. * **Get Kubernetes Namespace resources tree** - Fetches the resource tree of a specified Kubernetes Namespace * **Get Kubernetes resource** - Retrieves JSON serialized kubernetes resource. * **Get Kubernetes version** - Returns K8S and akuity agent version. * **Get Kubernetes workload logs** - Fetch logs from a Kubernetes workloads. * **Get Runbooks** - Retrieves runbook details by their names. Returns complete runbook content with General, Symptoms, Root cause, and Solution sections. * **Get Slack channels** - Returns list of channels where messages can be sent. * **Get conversation link** - Returns Markdown hyperlinks for the current conversation (open-conversation link plus deep-links to the related Argo CD application / namespace view). Use ONLY when a user asks for the link directly in chat. Do NOT use this to put links into Slack messages: Slack messages automatically get conversation and resource buttons attached to the thread root, so pasting links there would duplicate them. * **Get current time** - Return the current server time in RFC3339 format. Use this to compute absolute timestamps when reasoning about scheduled follow-ups. * **Get detailed code changes for specific files from the commits** - Get actual code patches for specific files that AI has identified as important for analysis * **Get incidents** - Retrieves JSON-serialized incidents for the given context. If the user is asking for a specific time range, the current time is 2026-08-14T21:21:47Z. * **Get incidents count** - Retrieves total number of incidents for the given context. If the user is asking for a specific time range, the current time is 2026-08-14T21:21:47Z. * **Get overview of the commits stats and changed files** - Get detailed code changes and file list for specific git commits (from freight commits or image OCI annotations) * **Get overview of the promotion changes** - Gather all promotion changes including git commits, images (with git info from OCI annotations), charts, and metadata for AI analysis * **Get release notes for GitHub releases** - Get release notes for GitHub releases between semantic versions (v1.0.0, v1.2.3) or git commits. Supports image version detection and automatic semantic version range analysis for comprehensive release notes. * **List Argo CD applications** - Retrieves a list of Argo CD applications. * **List Container Resources** - Get list of container resources managed by given instance, cluster or namespace * **List Deprecated APIs** - Get list of k8s deprecated apis managed by given instance or cluster * **List Git Repository Branches** - Returns a paginated list of branches in the git repository, with optional filtering by branch name. * **List Git Repository Files** - Returns list of files (optionally with content) in the git repository. * **List Git Repository Issues** - Returns a paginated list of issues for a Git repository. Supports filtering by state (open/closed/all), labels, assignee, and text search. * **List Images** - Get list images managed by given instance or cluster * **List K8s resources** - Get list of k8s resources managed by given instance, cluster or namespace * **List Kargo freight** - Queries for Freight in a Kargo project. Freight represents a collection of artifacts (container images, Helm charts, Git commits) that can be promoted through stages. Returns a flat list of freight. Every parameter must be supplied; pass an empty stage and an empty origins array to query freight for all stages. * **List Kargo promotions** - Retrieves a list of Promotions in a Kargo project. Promotions represent the movement of Freight from one Stage to another. Every parameter must be supplied; pass an empty stage to list every promotion in the project. * **List Kargo stages** - Retrieves a list of all Stages in a Kargo project. Stages represent environments in the delivery pipeline and define how freight is promoted through them. A stage's health check pins its Argo CD app to the stage's last promoted revision, so when stages share one git branch, promoting a later stage can flip earlier stages to Unhealthy ("does not match the desired revision") while the app itself is Synced and Healthy; the stage heals on its next promotion. Check the health output before treating that condition as a failure. * **List Kargo warehouses** - Retrieves a list of all Warehouses in a Kargo project. Warehouses watch for new artifacts (container images, Helm charts, Git commits) and produce Freight. * **List Stuck In Deletion Resources** - Get list of k8s resources stuck in deletion managed by given instance, cluster or namespace * **Patch Kubernetes resource** - Applies provided json serialized strategic merged patch to the given resource. * **Post Git Repository Issue Comment** - Posts a comment on an existing issue in a Git repository. * **Promote freight to stage** - Promotes specified freight to the target Kargo stage * **Refresh Kargo warehouse** - Triggers a refresh of a specific Kargo Warehouse to check for new artifacts. This forces the warehouse to scan its configured sources (Git repositories, container registries, Helm repositories) for new artifacts and produce new Freight. * **Resolve Incident** - Marks incident resolved with the given resolution description. * **Run refresh action on application** - The function refreshs the application. * **Run rollback action on application** - The function rollbacks the application. * **Run sync action on application** - The function syncs the application. * **Schedule task** - Schedule a future follow-up turn for this conversation after a delay (seconds), then STOP this turn — no further tool calls or reads are executed until the delay elapses and the conversation resumes. Prefer this after Argo CD mutations (patch, sync, refresh, scale), when waiting for rollout/Healthy status; do not immediately treat Progressing during pod restarts as failure. Also use for any LLM-managed delayed check-back: sync windows, Slack thread rechecks, periodic reinvestigation, or scheduled-task workflows. On resume, read fresh state and decide the next step. Allowed seconds: 10-1800; description should name the target and condition. * **Search Documentation** - Search the documentation for relevant information. Always include the conversation context to help refine the search. * **Sends a Slack message** - Sends a slack message. * **Store Runbook** - Stores a runbook to the ArgoCD instance configuration, the runbook will be used to automate the handling of future incidents * **Update Git Repository Files** - Commit files to the git repository. It creates a commit with the provided commit message. If the file doesn't exist, it will be created. * **Update Incident Root Cause** - Updates incident root cause. * **Update Incident Summary** - Updates incident summary. * **Update promotion analysis summary** - Updates promotion analysis with summary, risk level, and completion status. * **Verify Kubernetes resource patch** - Verifies if the provided json serialized strategic merged patch is valid. ## Tool Policies Tool Policies provide a critical security layer that gives you fine-grained control over the actions Akuity Intelligence can perform. By default, Akuity Intelligence is pre-configured with policies that allow the Akuity Agents to operate with reasonable independence, while still requiring human approval for sensitive or potentially risky actions. As an example the Akuity Agents are permitted to perform read-only actions, modify resources, and delete pods. The policies page allows you to customize this behavior, enabling you to define specific rules for when and how the Akuity Agents can execute function calls. To configure tool policies: * Navigate to Intelligence, click Settings in the top right corner. * From the left-hand menu, select the Tool Policies tab. * The Tool Policies section allows you to view, create, and manage your policies. ## Creating a Policy for User Approval A policy is composed of a Target (the action being taken), the Contexts (where the action applies), and an Action (the required approval level). To configure a rule that requires user approval for a specific operation, follow these steps: * Click Add to create a new policy row. * Define the Target of the operation you want to control: * Name: The name of the function the AI is attempting to call. You can use * as a wildcard to apply the policy to any function. * Arguments: A specific condition to match against the function's arguments. This allows for highly specific rules. For example, the expression `args.resourceID.kind == 'Deployment'` targets any action where the resource being acted upon is a Kubernetes Deployment. * Define the Contexts to limit the policy's scope. You can restrict the rule to specific: * Clusters * K8s Namespaces * Argo CD Applications * Kargo Projects * Runbooks * Set the final Action to Approve or Require Approval based on your needs. For instance, with the following example, whenever the On-Call Agent attempts to execute a function that performs a write operation(e.g., update a Deployment), it will pause and explicitly ask for user confirmation before proceeding, ensuring a human is always in the loop for critical operations. ![Tool policies](/img/intelligence_37.png) ![Patch Deployment](/img/intelligence_38.png) ## Multiple Tool Policies You can configure multiple policies. The Akuity Platform evaluates them in order, with the last matching policy taking precedence. For example, you could set a policy requiring approval for all tools, along with another that auto-approves the ArgoCD application refresh action. In this case, all tools would require approval except the refresh action. ![Multiple Tool Policies](/img/intelligence_39.png) ![Refresh App](/img/intelligence_40.png) --- ## Custom MCP Servers This feature lets organizations extend Akuity Intelligence by connecting customer-provided MCP servers to the existing tool-calling framework. With context-aware parameter mapping, the integration expands Akuity Intelligence from a Kubernetes/Argo CD specialist into a comprehensive DevOps automation assistant capable of cross-platform incident response and notification management. Before adding a Custom MCP Server, make sure you have: * A running MCP server reachable from the Akuity Platform. * Valid credentials (such as a bearer token, API key, or basic auth) authorized to call the server. ## Add Custom MCP Server ![Add Custom MCP Server](/img/intelligence_60.png) From the Intelligence → MCP Servers page, click Add Custom Server and fill in the following fields: * **Name** (required): A unique display name for this MCP server. * **Server URL** (required): The endpoint of the MCP server (for example, `https://mcp.example.com/mcp`). * **Transport Type** (required): The protocol used to communicate with the MCP server. Supported transports: * **Streamable HTTP** — recommended for new deployments. * **SSE** — for legacy MCP servers using Server-Sent Events. * **Credentials**: The authentication used when calling the server. Choose the method supported by your MCP server (for example, bearer token, API key header, or basic auth). Credentials are stored securely and are never exposed in the UI after they are saved. * **Tools**: The discovered tools are used when configuring `Context Mappings` so parameters can be bound to the right tool inputs. Ensure the MCP headers (transport, URL, and credentials) are correct before triggering tool discovery; otherwise the request will fail and no tools will be returned. ![Discover tools](/img/intelligence_64.png) * **Scope**: Binds the MCP server to the **Argo CD Instance** or **Kargo Instance** you select. The server's tools are exposed to Akuity Intelligence only when it operates within the selected instance. * **Context Mappings**: Context mappings let you bind an MCP server to specific contexts and pre-fill server parameters from the selected context. To configure a context mapping: 1. In the Context Mappings section, click Add Context Mapping. 2. Choose the context type **Argo CD Application**, **Argo CD Instance**, **Argo CD Cluster**, **Kargo Project**, or **Kubernetes Namespace**. 3. Map the relevant context fields to the server parameters. 4. Save the mapping. Once all fields are filled in and any context mappings are configured, click Save to register the server. Akuity Intelligence will connect to the server and attempt to discover its tools. ## Manage Custom MCP Server The MCP Servers page lists every registered Custom MCP Server alongside its connection status, scope, and available actions. Use this page to enable or disable servers, inspect discovered tools, and review configuration. ### Enable or disable a server ![Manage Custom MCP Server](/img/intelligence_61.png) Use the Enable switch in the server row to control whether Akuity Intelligence can call the server's tools. Disabling a server keeps its configuration intact but removes its tools from the available tool list until it is re-enabled. ### Inspect discovered tools ![List MCP Server Tools](/img/intelligence_62.png) Click the Tools icon in the server row to open the tool list. For each tool, the panel displays: * The tool name and description reported by the MCP server. * The input parameter schema, including parameter names, types, and whether each parameter is required. * Any context mappings that pre-fill parameter values from the active resource. ## Use Custom MCP Server ![Using Notion MCP Server](/img/intelligence_63.png) Once a Custom MCP Server is installed and enabled, its tools are available to Akuity Intelligence alongside the built-in tools. Follow these steps to use a Custom MCP Server: 1. Confirm the server shows a `Connected` status on the MCP Servers page. If it is not connected, Akuity Intelligence cannot call its tools. 2. Open a chat with Akuity Intelligence from the Floating Button or from the context of a specific resource (Argo CD Application, Kargo Project, or Kubernetes Namespace). Make sure the resource has been configured in the server's `Context Mappings` so Akuity Intelligence can resolve the right parameters. 3. Ask Akuity Intelligence to perform a task that maps to one of the server's tools (for example, "open an incident in PagerDuty for this application" or "post a deployment summary to Slack"). Akuity Intelligence selects the appropriate tool, applies the configured context mappings to pre-fill parameters, and calls the MCP server. 4. Review the response to confirm the tool call succeeded. --- ## MCP Servers --- ## Akuity Intelligence Akuity Intelligence provides real-time visibility, AI-powered troubleshooting, and auto-remediation for your Kubernetes environment. Key capabilities include: * **Real-time Insights and Dashboards**: Gain unparalleled visibility into your applications and infrastructure with built-in, multi-cluster dashboards. These provide a consolidated, real-time view of metrics, logs, and event streams, enabling teams to quickly understand system health and identify issues early. * **Akuity Agents**: Leverage a powerful Akuity Agents to automate troubleshooting and remediation. The Akuity Agents analyze operational data to pinpoint the root cause of failures and can automatically execute predefined runbooks to resolve incidents, significantly reducing manual intervention and improving application resilience. The Akuity Agents include the Deployment Advisor, the On-Call Agent, and the Promotion Advisor. --- ## Getting Started(07-self-hosted) This documentation is designed to help you get started with the Akuity Self Hosted Platform. This is a comprehensive guide that will walk you through the process of setting up and using the Akuity Platform on your own infrastructure. If you have any questions or need help, please reach out to your designated support contact or in your communication channel (Slack, Teams, etc.) ## Prerequisites Before starting, you will need two key pieces of information: - Your Akuity Platform license key - A key for the Akuity Platform OCI registry ### Logging into the registry ```console # This will prompt you for your registry key helm registry login us-docker.pkg.dev -u _json_key_base64 ``` ## Infrastructure Requirements The Akuity Platform is designed to run on a dedicated Kubernetes cluster. Generally speaking, any cluster, no matter where it is hosted, you will need the following infrastructure available in addition to the Kubernetes cluster: - A postgres database accessible from the Kubernetes cluster - Kubernetes network policy engine (e.g. Calico, Cilium, etc.) - A network-level load balancer to route traffic to the platform - DNS configured to point traffic to the load balancer - An OIDC identity provider for authentication (e.g. Google, Okta, etc.) - A wildcard TLS certificate for the domain you are using for the platform (or the ability to generate one on the fly using cert-manager) - SMTP (optional) - A cluster autoscaler (optional) The next sections cover more information on each of these requirements. Where applicable, you can select for more specific for many of the commonly used cloud providers. If you have any other questions, please reach out to Akuity support. ### Network Security Akuity Platform deploys `NetworkPolicy` resources in order to ensure ingress and egress connectivity to Pods are allowed on an as-needed basis, and to disallow cross-namespace communication between tenants. For this to work, a Kubernetes network policy engine must be installed to enforce these policies. **AWS** Akuity recommends using the [AWS VPC-CNI](https://docs.aws.amazon.com/eks/latest/userguide/cni-network-policy.html) for a policy engine. As an alternative, [Calico](https://projectcalico.docs.tigera.io/) can also be used with the AWS VPC-CNI. #### Calico Installation If you choose to use Calico, follow the [installation instructions](https://docs.tigera.io/calico/latest/argo-cd/getting-started/kubernetes/managed-public-cloud/eks) provided by Tigera for EKS. **GCP** A GKE cluster will need to have the network policy engine enabled. This can be done even if the cluster was already created. See the [GCP docs](https://cloud.google.com/kubernetes-engine/docs/how-to/network-policy) for more information. **Azure** Akuity recommends [Calico](https://projectcalico.docs.tigera.io/) for network policies in Azure. #### Calico Installation **Note:** Calico should be enabled during cluster creation. You can follow the Microsoft documentation [here](https://learn.microsoft.com/en-us/azure/aks/use-network-policies#create-an-aks-cluster-and-enable-network-policy) for enabling Calico during cluster creation. **On-Prem** Akuity recommends [Calico](https://projectcalico.docs.tigera.io/) for network policies in an On-Prem cluster, but any Kubernetes network policy engine that is compatible with your Kubernetes cluster should work. ### Kubernetes Auto-Scaling As Argo CD instances are created, and as more clusters connect to Akuity Platform, additional capacity is needed in the host control-plane cluster. Akuity Platform has no direct dependency on a specific autoscaler, but deploys HPA resources to automatically scale based on cpu/memory load. A Kubernetes cluster autoscaler allows for automatically adding compute capacity to the cluster. There are two popular solutions for autoscaling, in addition to vendor-specific solutions: 1. [Cluster Autoscaler](https://github.com/kubernetes/autoscaler) 2. [Karpenter (AWS and Azure only)](https://karpenter.sh/) **AWS** If running on EKS, Akuity recommends Karpenter as it allows better flexibility for right-sizing the EC2 sizes according to the capacity. The following EC2 instance types (Nitro-based to support prefix delegation) are recommended: - t3.large - t3.xlarge - t3a.large - t3a.xlarge - t3a.2xlarge - m5.large - m5.xlarge - m5a.large - m5a.xlarge - c5.large - c5.xlarge - r6a.large **GCP** GKE clusters can use the [Cluster Autoscaler](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-autoscaler) to automatically scale the cluster based on resource usage. It is also possible to use [Cluster Autoscaler](https://github.com/kubernetes/autoscaler) **Azure** Akuity recommends using [Cluster Autoscaler](https://github.com/kubernetes/autoscaler) **On-Prem** For on-prem clusters, Akuity recommends using one of the open source solutions mentioned above. #### Kubernetes Nodes If auto-scaling is not used, then we recommend having a minimum of 3 nodes with a minimum of 2 vCPUs and 8GB RAM for each node. This number is highly variable and dependent on the number of applications, number of control planes managed by AKP, etc. This is something which you will need to keep a close eye on and tune accordingly depending on your workload. ### PostgreSQL Database Akuity Platform requires a PostgreSQL database to store its data. The database can be self-hosted or be a managed service provided by your cloud provider. The database must be accessible from the Kubernetes cluster where the Akuity Platform is installed and securing the connection to the database is left to the user. No matter which option you choose, the database must be configured with the following requirements: - Engine: PostgreSQL - Version: 14.6+ Regardless of your cloud provider, the appropriate instance class/size is highly variable and depends on a number of factors: - Number of Argo CD instances - Number of total clusters across instances - Number of applications across instances **AWS** If using an Amazon-managed database, Akuity recommends using Amazon Aurora. #### Requirements - Engine: Amazon Aurora PostgreSQL-Compatible Edition - Version: 14.6, 14.7, 14.8 - Default parameter groups: aurora-postgresql14 - [Enforce TLS](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Security.html#AuroraPostgreSQL.Security.SSL.Requiring) ([certificates](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/UsingWithRDS.SSL.html)) with `“rds.force_ssl” = “1”` #### Recommended - Encryption enabled - Aurora Replica or Reader node in a different AZ for the purposes of high-availability failover and to provide read-only instances. #### DB Instance Class: The following are examples of configurations that have been tested: | Limits | DB Instance Class | | :---- | :---- | | 10 instances, 10 clusters, 100 applications | db.t4g.medium (2 vCPU, 4 GiB RAM) | | 5 instances, 1000 Clusters, 5000 Applications | db.r6g.xlarge (4 vCPU, 32 GiB RAM) | :::note The Aurora Serverless v2 instance class is not recommended due to cost inefficiencies. Akuity Platform’s database load characteristics are constant / not bursty, so as a result Aurora Serverless v2 costs much more to support the same or fewer number of Argo CD instances, clusters, and applications. ::: #### Networking Akuity recommends the following: - [Private subnets](https://aws.github.io/aws-eks-best-practices/networking/subnets/#using-private-and-public-subnets) for both the Kubernetes workloads and database VPC. - While it is possible/supported for the RDS database to be provisioned in the same VPC as the EKS VPC, you may consider RDS database in its own VPC, and connected via [Transit Gateway](https://aws.amazon.com/transit-gateway/?whats-new-cards.sort-by=item.additionalFields.postDateTime&whats-new-cards.sort-order=desc). The benefit of this separation allows for the EKS cluster to be more easily replaced, which is possible since Akuity Platform only runs stateless workloads. **GCP** If using a Google-managed database, Akuity recommends using Cloud SQL. #### Requirements: - Engine: Cloud SQL PostgreSQL - Version: 14 #### Recommended: - Replica or Reader node in a different AZ for the purposes of high-availability failover and to provide read-only instances. #### DB Instance Class: The following are examples of configurations that have been tested: | Limits | DB Instance Size | | :---- | :---- | | 10 instances, 10 clusters, 100 applications | 2 vCPU, 4 GiB RAM | | 5 instances, 1000 Clusters, 5000 Applications | 4 vCPU, 32 GiB RAM | **Azure** If using an Azure-managed database, Akuity recommends using Azure Database for PostgreSQL. #### Requirements: - Engine: Azure Database for PostgreSQL Flexible Server - Version: 14 The extensions need to be [allowlisted](https://learn.microsoft.com/en-us/azure/postgresql/flexible-server/concepts-extensions#how-to-use-postgresql-extensions) in the database before starting. #### Recommended: - Replica or Reader node in a different AZ for the purposes of high-availability failover and to provide read-only instances. #### DB Instance Class: The following are examples of configurations that have been tested: | Limits | DB Instance Class | | :---- | :---- | | 10 instances, 10 clusters, 100 applications | Standard\_D2ds\_v5 (2 vCPU, 8 GiB RAM) | | 5 instances, 1000 Clusters, 5000 Applications | Standard\_D8ds\_v5 (8 vCPU, 32 GiB RAM) | **On-Prem** If self-hosting the database, Akuity recommends using a PostgreSQL database that meets the requirements above in addition to the following #### Recommended: - Encryption enabled - Replica or Reader node in a different AZ/datacenter/rack for the purposes of high-availability failover and to provide read-only instances. #### DB Instance Size: The following are examples of configurations that have been tested: | Limits | DB Instance Class | | :---- | :---- | | 10 instances, 10 clusters, 100 applications | 2 vCPU, 4 GiB RAM | | 5 instances, 1000 Clusters, 5000 Applications | 4 vCPU, 32 GiB RAM | #### Non-Superuser Permissions If your database user is not running as a superuser or equivalent (e.g., `rds_superuser` on RDS), you will need to grant additional permissions. The user must have the `CREATEROLE` privilege and ability to create schemas, as well as being allowed to `GRANT` connect privileges to other users. Substitute `admin_user` for the actual role you intend to use. The example below assumes the installation of all the database objects to the `akuity` schema; the Akuity Platform default is `public` for legacy reasons but new installations should install the Akuity Platform to a schema other than `public`. ```sql -- CREATEROLE is a requirement since we need to create a user per instance. CREATE USER admin_user WITH PASSWORD '' CREATEROLE; -- We need this to be able to perform database migrations. GRANT CREATE ON DATABASE TO admin_user; -- The admin user also needs to be able to GRANT CONNECT to the provisoned instance user, so the provisioned user can actually connect to the database. GRANT CONNECT ON DATABASE TO admin_user WITH GRANT OPTION; GRANT USAGE ON SCHEMA akuity TO admin_user; GRANT CREATE ON SCHEMA akuity TO admin_user; GRANT ALL ON ALL TABLES IN SCHEMA akuity TO admin_user; GRANT ALL ON ALL SEQUENCES IN SCHEMA akuity TO admin_user; GRANT ALL ON ALL FUNCTIONS IN SCHEMA akuity TO admin_user; ALTER DEFAULT PRIVILEGES IN SCHEMA akuity GRANT ALL ON TABLES TO admin_user; ALTER DEFAULT PRIVILEGES IN SCHEMA akuity GRANT ALL ON SEQUENCES TO admin_user; ALTER DEFAULT PRIVILEGES IN SCHEMA akuity GRANT ALL ON FUNCTIONS TO admin_user; ``` ### Load Balancing and Ingress The Akuity Platform installation bundles [Traefik Ingress Controller](https://github.com/traefik/traefik) as part of its installation. Upgrades of Traefik and CRDs will be handled as part of upgrades of Akuity Platform. **AWS** Akuity Platform assumes the presence of [AWS Load Balancer Controller](https://github.com/kubernetes-sigs/aws-load-balancer-controller) and will provision a Kubernetes Service with NLB specific annotations needed by the platform. e.g.: ```yaml apiVersion: v1 kind: Service metadata: name: traefik namespace: traefik-external annotations: service.beta.kubernetes.io/aws-load-balancer-backend-protocol: tcp service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: ip service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing service.beta.kubernetes.io/aws-load-balancer-target-group-attributes: preserve_client_ip.enabled=true service.beta.kubernetes.io/aws-load-balancer-type: external ``` An NLB is used (as opposed to ALB) for the cloud load balancer since: - Traffic to the Akuity Platform is a mix of protocols (HTTP, TCP, gRPC) - Routing decisions are configured at Ingress level, not at the Load Balancer **GCP** The Akuity Platform will provision a Kubernetes LoadBalancer Service (which will create a GCP Network Load Balancer). GCP Load Balancer specific annotations can be added to this service to achieve desired configurations. **Azure** Akuity Platform will provision a Kubernetes LoadBalancer Service (which will create an Azure Load Balancer). Azure Load Balancer specific annotations can be added to this service to achieve desired configurations such as making the load balancer [internal only](https://learn.microsoft.com/en-us/azure/aks/internal-lb). **On-Prem** If using an on-prem cluster, that cluster will need to be able to create a LoadBalancer Service that an external load balancer can route traffic to. ### TLS The default behavior of Akuity Platform requires a public certificate and private key of a wildcard TLS certificate. TLS is needed to terminate inside cluster at Ingress/Traefik – not at the NLB. This is due to the fact that, by default, Akuity Platform leverages features of Traefik which require passthrough behavior to Ingress (e.g. IP allowlist, websocket support, HTTP2/gRPC). :::note For advanced use cases where you need to bring your own ingress controller or have a hard requirement on terminating TLS at the load balancer, it is possible to disable TLS termination. See the [Bring Your Own Ingress](./10-bring-your-own-ingress.md) document for more information. ::: The wildcard certificate given to Akuity Platform must be valid for the following domains (replace `akuity.example.com` with your own domain): * `akuity.example.com` * `*.cd.akuity.example.com` * `*.cdsvcs.akuity.example.com` * `*.kargo.akuity.example.com` * `*.kargosvcs.akuity.example.com` Akuity Platform does not have any requirements on how the certificate is provisioned. TLS certificates can be obtained in different ways. Some options include: 1. Purchased from a traditional certificate providers (e.g. Verisign, DigiCert) 2. Free, time-limited (90 day) certificates from Let’s Encrypt If the TLS Secret is managed separately and not supplied to the Helm chart (e.g. generated by cert-manager, deployed via External Secret) the resulting secret should be named `akuity-platform-tls` in the `traefik-external` namespace. Akuity Platform will assume the presence of this Secret so that it can be referenced by Traefik ingress. #### Cert-Manager (optional) If you are using cert-manager to manage your TLS certificates, the following example shows how to do so with a Let's Encrypt issuer. These instructions can be adapted for other issuers as well. ```yaml apiVersion: cert-manager.io/v1 kind: Issuer metadata: name: letsencrypt-prod spec: acme: email: admin@example.com privateKeySecretRef: name: letsencrypt-prod server: https://acme-v02.api.letsencrypt.org/directory solvers: - dns01: route53: region: us-east-1 selector: dnsZones: - akuity.example.com - cd.akuity.example.com - cdsvcs.akuity.example.com - kargo.akuity.example.com - kargosvcs.akuity.example.com ``` ```yaml apiVersion: cert-manager.io/v1 kind: Certificate metadata: name: akuity.example.com namespace: akuity-platform spec: dnsNames: - akuity.example.com - '*.cd.akuity.example.com' - '*.cdsvcs.akuity.example.com' - '*.kargo.akuity.example.com' - '*.kargosvcs.example.com' issuerRef: name: letsencrypt-prod # This secret name is important, as it is the name that Akuity Platform expects secretName: akuity-platform-tls ``` ### DNS Akuity Platform requires DNS to be configured for the domain you are using for the platform. When the platform creates resources: Argo CD instances will be provisioned with human-friendly and reconfigurable DNS names like: - `myargocd-1.cd.akuity.example.com` - `myargocd-2.cd.akuity.example.com` Agent components will connect to static, ID specific DNS names like: - `x8ax38dmb1d81h-cplane.cdsvcs.akuity.example.com` - `x8ax38dmb1d81h-cache.cdsvcs.akuity.example.com` Configuring DNS is platform specific and instructions are specified below. :::tip To automate the creation of these records, [External DNS](https://github.com/kubernetes-sigs/external-dns) can be used to automatically create the records by adding additional annotations to the NLB Service object. ```yaml apiVersion: v1 kind: Service metadata: name: traefik namespace: traefik-external annotations: external-dns.alpha.kubernetes.io/alias: "true" external-dns.alpha.kubernetes.io/hostname: | '*.cd.akuity.example.com.,*.cdsvcs.akuity.example.com.' ``` ::: **AWS** Akuity Platform requires a Route53 Hosted Zone (e.g. `akuity.example.com`) with the following records pointing to the NLB hostname/IP: | Record Name | Type | Value/Route traffic to | | :---- | :---- | :---- | | `akuity.example.com` | A | ALIAS to NLB | | `*.cd.akuity.example.com` | A | ALIAS to NLB | | `*.cdsvcs.akuity.example.com` | A | ALIAS to NLB | | `*.kargo.akuity.example.com` | A | ALIAS to NLB | | `*.kargosvcs.akuity.example.com` | A | ALIAS to NLB | **GCP** Akuity Platform requires a Cloud DNS Hosted Zone (e.g. `akuity.example.com`) with the following records pointing to the NLB hostname/IP: | Record Name | Type | Value/Route traffic to | | :---- | :---- | :---- | | `akuity.example.com` | A | Traefik Load Balancer Service | | `*.cd.akuity.example.com` | A | Traefik Load Balancer Service | | `*.cdsvcs.akuity.example.com` | A | Traefik Load Balancer Service | | `*.kargo.akuity.example.com` | A | Traefik Load Balancer Service | | `*.kargosvcs.akuity.example.com` | A | Traefik Load Balancer Service | **Azure** Akuity Platform requires a DNS Zone (e.g. `akuity.example.com`) with the following records pointing to the load balancer hostname/IP: | Record Name | Type | Value/Route traffic to | | :---- | :---- | :---- | | `akuity.example.com` | A | Traefik Load Balancer Service | | `*.cd.akuity.example.com` | A | Traefik Load Balancer Service | | `*.cdsvcs.akuity.example.com` | A | Traefik Load Balancer Service | | `*.kargo.akuity.example.com` | A | Traefik Load Balancer Service | | `*.kargosvcs.akuity.example.com` | A | Traefik Load Balancer Service | **On-Prem** Akuity Platform requires a DNS Zone (e.g. `akuity.example.com`) with the following records pointing to the load balancer hostname/IP: | Record Name | Type | Value/Route traffic to | | :---- | :---- | :---- | | `akuity.example.com` | A | Traefik Load Balancer Service | | `*.cd.akuity.example.com` | A | Traefik Load Balancer Service | | `*.cdsvcs.akuity.example.com` | A | Traefik Load Balancer Service | | `*.kargo.akuity.example.com` | A | Traefik Load Balancer Service | | `*.kargosvcs.akuity.example.com` | A | Traefik Load Balancer Service | ### OIDC Identity Provider Akuity Platform requires login via an OIDC-compliant identity provider (IdP) using OAuth 2.0 login flow. Akuity Platform can be configured to integrate directly with an OIDC provider, or through [Dex](https://dexidp.io/) as an intermediary. Dex is bundled as an ***optional*** component of the helm chart. You may wish to enable Dex for the following reasons: - Dex supports local, static users/passwords with dummy email addresses. This is useful for getting started, reducing upfront requirements, and for testing purposes. - If obtaining a client application from your organization’s IdP is a difficult process or not possible, Dex can be used as an IdP to other services you may have more access to, such as GitHub. - If you are using Azure AD and you wish to limit Akuity Platform authentication through Azure AD groups. Dex is able to perform translation of Azure AD groups to OIDC claims, and limit logins to particular groups (without any configuration on the IdP side). ### SMTP SMTP is used to send emails notifying users that they have been invited to an organization. It is optional. If not configured users will not be notified about a pending invite but can still navigate to their account page to accept an invite. ## Installation For longer term management and updates, we recommend using Argo CD to manage the platform. However, there is a chicken and egg problem as you need to do the initial installation and creation of the manifests before they can be managed by Argo CD. To assist with this we have a scaffolding for bootstrapping your installation. To use it, run the following command in a directory where you want to keep the manifest files: ```console curl -fsSL -o quickstart.zip https://dl.akuity.io/self-hosted/quickstart.zip && unzip quickstart.zip && rm quickstart.zip # Feel free to rename the directory if you want before continuing cd quickstart helm pull oci://us-docker.pkg.dev/akuity/akp-sh/charts/akuity-platform --untar --untardir charts ``` This directory contains a `values.yaml` file with some of the most common configuration items available for you to customize. You will need to edit this file and fill out the details specific to your installation. If you need to make additional customizations that are not supported by the chart, you can use the `kustomization.yaml` file to make those last-mile modifications. Once you have configured your values and customizations, use the following command to deploy the Akuity Platform: ```console kustomize build --enable-helm | kubectl apply -f - ``` Once you have run this command, the Akuity Platform will be installed in your cluster. You can also commit the manifests to your Git repository and use Argo CD to manage the platform going forward. ## Changelogs You can find the changelogs for the Self Hosted Platform in the [changelog](../06-changelog/30-selfhosted/index.mdx) section of the documentation. --- ## Bring Your Own Ingress The Akuity Platform requires the use of several features provided by the [Traefik](https://doc.traefik.io/traefik/) ingress controller. As such, it is installed and managed as part of the self-hosted platform. For most installations, you can use this Ingress alongside your current ingress or on its own. However, some use cases require you to use your own ingress controller for compliance or other reasons such as controlling TLS termination. This document describes how bring your own ingress controller to the Self Hosted Akuity Platform. This document assumes familiarity with Kubernetes networking and Ingress resources. ## Bringing your own ingress To bring your own ingress controller, you'll need to disable TLS termination in the chart. Doing this will setup the Traefik ingress controller to use an internal `ClusterIP` address rather than a public `LoadBalancer`. It also means your ingress controller will need to handle TLS termination for your connections. Once the Helm chart is installed, you need to create several Ingress resources that route to the Traefik `Service` inside the cluster. This service is found in the `traefik-external` namespace once the self-hosted platform is installed. There is 1 address and 4 wildcard addresses that need to be routed to the Traefik ingress controller. The fully qualified address is for the Self Hosted Platform UI. This is also set as part of installing the chart and will likely be something like `akuity.mycompany.com` The wildcard addresses by default will be based off of the top level domain you set above. So, using `akuity.mycompany.com` as an example, the wildcard addresses will be: - `*.cdsvcs.akuity.mycompany.com` - `*.cd.akuity.mycompany.com` - `*.kargo.akuity.mycompany.com` (if using the Kargo feature) - `*.kargosvcs.akuity.mycompany.com` (if using the Kargo feature) :::info If you are using other domain names or subdomains, you will need to adjust the wildcard addresses to match those addresses instead. For example, if you wanted your ArgoCD instances available on the `.argocd.mycompany.com` domain for each team, you would need to setup an ingress that routes `*.argocd.mycompany.com` to the `traefik` service in the `traefik-external` namespace. ::: What you end up with is something that should look like this: ```mermaid graph LR subgraph "User's Ingress Namespace" userIng1["Ingress: akuity.mycompany.com"] userIng2["Ingress: *.cdsvcs.akuity.mycompany.com"] userIng3["Ingress: *.cd.akuity.mycompany.com"] userIng4["Ingress: *.kargo.akuity.mycompany.com"] userIng5["Ingress: *.kargosvcs.akuity.mycompany.com"] end subgraph "traefik-external Namespace" traefikSvc["Service:\ntraefik:80"] traefikPod["Traefik Ingress Controller"] end subgraph "Akuity managed namespaces" akuityUI["Akuity Platform"] akuityCdSvc["Akuity Agent Services"] akuityKargoSvc["Akuity Kargo Services"] end userIng1 --> traefikSvc userIng2 --> traefikSvc userIng3 --> traefikSvc userIng4 --> traefikSvc userIng5 --> traefikSvc traefikSvc --> traefikPod traefikPod --> akuityUI traefikPod --> akuityCdSvc traefikPod --> akuityKargoSvc classDef ingress fill:#f9f,stroke:#333,stroke-width:2px,color:#000; classDef service fill:#bbf,stroke:#333,stroke-width:2px,color:#000; classDef controller fill:#bfb,stroke:#333,stroke-width:2px,color:#000; classDef platform fill:#fbb,stroke:#333,stroke-width:2px,color:#000; class userIng1,userIng2,userIng3,userIng4,userIng5 ingress; class traefikSvc service; class traefikPod controller; class akuityUI,akuityCdSvc,akuityKargoSvc platform; ``` ## Example using Nginx Ingress As there are many ingress controllers and configurations, it is impossible to provide a complete example for all use cases. However, the following example shows how to use the Nginx ingress controller with the Self Hosted Akuity Platform and should be adaptable to your ingress controller of choice. This example uses the same "akuity.mycompany.com" domain as above. It also assumes you have the Nginx ingress controller installed and running with an ingress class name of `nginx`. :::info For ease of use, the following example creates the Ingresses in the `traefik-external` namespace. You can create them in any namespace, but you'll need to configure your ingress controller and/or network policies to allow cross-namespace routing ::: ```yaml --- apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: akuity-external-main namespace: traefik-external spec: ingressClassName: nginx rules: - host: "akuity.mycompany.com" http: paths: - backend: service: name: traefik port: number: 80 path: / pathType: Prefix --- apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: akuity-external-cdsvcs namespace: traefik-external annotations: # Recommended but not required annotations as the agent tunnel has a long-running connection nginx.ingress.kubernetes.io/proxy-read-timeout: "3600" nginx.ingress.kubernetes.io/proxy-send-timeout: "3600" spec: ingressClassName: nginx rules: - host: "*.cdsvcs.akuity.mycompany.com" http: paths: - backend: service: name: traefik port: number: 80 path: / pathType: Prefix --- apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: akuity-external-cd namespace: traefik-external spec: ingressClassName: nginx rules: - host: "*.cd.akuity.mycompany.com" http: paths: - backend: service: name: traefik port: number: 80 path: / pathType: Prefix --- apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: akuity-external-kargo namespace: traefik-external spec: ingressClassName: nginx rules: - host: "*.kargo.akuity.mycompany.com" http: paths: - backend: service: name: traefik port: number: 80 path: / pathType: Prefix --- apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: akuity-external-kargosvcs namespace: traefik-external spec: ingressClassName: nginx rules: - host: "*.kargosvcs.akuity.mycompany.com" http: paths: - backend: service: name: traefik port: number: 80 path: / pathType: Prefix ``` ## Caveats When you disable TLS termination and bring your own ingress, by default all ArgoCD clusters will be created with the Redis tunneling feature enabled. This is due to the difficulty (and sometimes impossibility) of passing through a TLS connection in a double ingress scenario or with some load balancers that handle TLS termination. In practice, you will not see any difference from a normal Redis connection that routes through your ingress as it will instead route through the tunnel connection established by the Akuity agent. You can disable redis tunneling on Clusters you create, but be aware that this is not recommended practice and must be self-supported rather than supported by Akuity. --- ## Multi-Region Multi-region functionality in the Akuity Platform enables the distribution of Argo CD instances across clusters in different regions and/or cloud providers, allowing you to select where each Argo CD instance is created. This is done using the sharding feature of the Akuity Platform. :::danger Multi-regional deployment of the Akuity Platform is an advanced function. Review this page in its entirety and ensure that you understand the requirements and limitations of this feature before proceeding. Contact support before proceeding if anything is unclear. ::: ## Considerations and Limitations - Multi-regional deployment of the Akuity Platform does not constitute a backup or high-availability solution. - Argo CD instances cannot be moved to another region after creation. - Region names cannot not be modified once Argo CD instances are deployed to it. - Region assignments to Organizations require manual database changes. - Argo CD URLs will use a unique regional subdomain. ## Requirements - A working Akuity Platform installation in your primary region. - At least 1 organization created in the Akuity Platform. - At least 1 additional Kubernetes cluster. - At least 1 database instance per additional Kubernetes cluster. - Network connectivity to the database instance in your primary region from all non-primary regions. - A DNS zone for each region matching the region's name. - A wildcard SSL certificate for each region with SANs matching the region's name. ## Enable Multi-Region ### Helm Values The Helm values used for your **non-primary** region/s will typically match your primary region. The only exception is your **non-primary** region/s should have `.platformController.shard` set to the name desired for that region (ex. `us-west`). :::info The Helm value set for `.platformController.shard` is incorporated into the FQDN for instances in that region. For example, instances assigned to a shard named `us-west` would use an FQDN like \.cd.**us-west**.mydomain.com. Instances assigned to a shard named `us-central` would use an FQDN like \.cd.**us-central**.mydomain.com. Instances not assigned to a shard will use the usual FQDN form of \.cd.mydomain.com. You will need to ensure that the SANs for the SSL certificate deployed in a region match the FQDNs that will be used in that region. ::: ### Kustomizations #### Adjusting Database Configurations of Non-Primary Shards Each **non-primary** region/shard will need it's own database in addition to being able to access the database configured in the primary region. The K3S database connection strings for each shard will need to be overridden to make the shard connect to its own database. To make this change using Kustomize, use the following patches: ``` patches: - target: kind: Secret name: akuity-platform patch: |- - op: replace path: /data/K3S_DB_CONNECTION value: - op: replace path: /data/K3S_RO_DB_CONNECTION value: ``` :::note Replace `` with a base64'd database connection string for that region/shard. Example: ``` echo -n 'host=db.us-west.mydomain.com port=5432 sslmode=require dbname=postgres user=myuser password=mypassword' | base64 ``` ::: #### (Optional) Using a Custom Shard Name in the Primary Region To assign a unique shard name to your **primary region**, you can apply the follow Kustomize patch: ``` patches: - target: kind: Deployment name: platform-controller patch: |- - op: add path: /spec/template/spec/containers/0/args/- value: --shard= ``` :::danger If the primary region is configured using a unique shard name, instances created in an organization without any assigned shards will be undeployable. Note that the primary region can still be used alongside other shards without specifying a unique shard name. ::: ### Assigning Shards to Organizations In order to assign an Argo CD instance to a region, that region's shard must first be assigned to an organization in the Akuity Platform. To assign shards to an organization, you must update the database in the **primary region** and explicitly specify which shards each organization is allowed to deploy to. 1. Connect to the database. ``` psql "host=db.us-west.mydomain.com port=5432 sslmode=require dbname=postgres user=myuser password=mypassword" ``` 1. Update the organization with the shards you wish to assign ``` UPDATE organization SET feature_gates='{"shards":["",""]}' WHERE name=''; ``` :::info The JSON list of shard names should be expanded to contain the names of all desired shards to be made available to an organization. ::: :::info The primary region can be made an option in the Region dropdown even if a unique shard name has not been specified. If a unique name has not been specified for the primary region, this can be done by setting one of the shard names in the `shards` list of the SQL query above as empty (`""`). The primary region will then become an option during instance creation with the region name `us0`. ::: ### Creating an Instance Once sharding has been enabled for an organization, you will see a new Region dropdown with a list of the shard names you assigned to the organization in the previous step. ![Region dropdown](./region.png) :::note If you are missing this dropdown, verify that you assigned **at least** 2 shards to the organization in the previous section. ::: #### Validation To verify your instance has been or is being created in the selected region: 1. Change your `kubectl` context to the region/shard you assigned your instance to. 1. Run `kubectl get ns`. 1. A new `argocd-` namespace should appear. --- ## Images List If you are running a self-hosted version of the Akuity Platform, you might want to re-tag the images to use a different registry. The following images are used by the Self-Hosted Akuity Platform. This list is not exhaustive and may change over time. :::tip Akuity publishes [OpenVEX](https://openvex.dev/) vulnerability assessments and signed attestations for the public images below (the agent, Argo CD, and Kargo). See [Verifying Images](../02-akuity-portal/01-security/30-verifying-images.md) to apply them during scanning or verify them with cosign. ::: ## Component Versions Some images are tagged based on the component version, irrespective of the Akuity Platform version. The following images depend on the component version: - `quay.io/argoproj/argocd:`: Repository used for OSS ArgoCD images, the tag required would match the version of OSS ArgoCD you are using. Example: `quay.io/argoproj/argocd:v2.14.9`. - `quay.io/akuity/argocd:`: Repository used for the Enterprise ArgoCD images, the tag required would match the version of Enterprise ArgoCD you are using. Example: `quay.io/akuity/argocd:v2.14.9-ak.53` - `quay.io/argoprojlabs/argocd-image-updater:`: Repository for ArgoCD Image Updater images. The tag must match the version of ArgoCD Image Updater you are using, which can be configured in the Image Updater section of your AKP ArgoCD Instance Settings. Example: `quay.io/argoprojlabs/argocd-image-updater:v0.14.0` - `ghcr.io/akuity/kargo:`: Repository used for the Kargo images, the tag required would match the version of Kargo you are using. Example: `ghcr.io/akuity/kargo:v1.4.0` - `quay.io/akuity/agent:`: Repository used for the Agent images, the tag required would match the version of the Agent you are using. Example: `quay.io/akuity/agent:0.5.57` - `us-docker.pkg.dev/akuity/akp-sh/agent-server:latest`: Repository used for the Agent Server images. In addition to the above images, the images listed in the next section are dependent on the Akuity Platform version you are using. ## Image List ### v0.32.0 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/edoburu/pgbouncer:v1.25.1-p0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.3.8-alpine - quay.io/akuity/rancher/k3s:v1.33.8-k3s1 - quay.io/akuity/redis:7.2.11-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - quay.io/argoproj/argo-rollouts:v1.8.3 - quay.io/argoproj/argo-rollouts:v1.9.0 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.96 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.31.2 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/edoburu/pgbouncer:v1.25.1-p0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.3.8-alpine - quay.io/akuity/rancher/k3s:v1.33.8-k3s1 - quay.io/akuity/redis:7.2.11-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - quay.io/argoproj/argo-rollouts:v1.8.3 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.95 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.31.1 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/edoburu/pgbouncer:v1.25.1-p0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.3.8-alpine - quay.io/akuity/rancher/k3s:v1.33.8-k3s1 - quay.io/akuity/redis:7.2.11-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - quay.io/argoproj/argo-rollouts:v1.8.3 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.94 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.31.0 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/edoburu/pgbouncer:v1.25.1-p0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.3.8-alpine - quay.io/akuity/rancher/k3s:v1.33.8-k3s1 - quay.io/akuity/redis:7.2.11-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - quay.io/argoproj/argo-rollouts:v1.8.3 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.94 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.30.1 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/edoburu/pgbouncer:v1.25.1-p0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.3.8-alpine - quay.io/akuity/rancher/k3s:v1.33.8-k3s1 - quay.io/akuity/redis:7.2.11-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - quay.io/argoproj/argo-rollouts:v1.8.3 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.90 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.29.1 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/edoburu/pgbouncer:v1.24.0-p0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.2.6-alpine - quay.io/akuity/rancher/k3s:v1.33.5-k3s1 - quay.io/akuity/redis:7.2.11-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - quay.io/argoproj/argo-rollouts:v1.8.3 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.80 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.29.0 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/edoburu/pgbouncer:v1.24.0-p0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.2.6-alpine - quay.io/akuity/rancher/k3s:v1.33.8-k3s1 - quay.io/akuity/redis:7.2.11-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - quay.io/argoproj/argo-rollouts:v1.8.3 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.82 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.28.2 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/edoburu/pgbouncer:v1.24.0-p0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.2.6-alpine - quay.io/akuity/rancher/k3s:v1.33.5-k3s1 - quay.io/akuity/redis:7.2.11-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - quay.io/argoproj/argo-rollouts:v1.8.3 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.80 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.28.1 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/edoburu/pgbouncer:v1.24.0-p0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.2.6-alpine - quay.io/akuity/rancher/k3s:v1.33.5-k3s1 - quay.io/akuity/redis:7.2.11-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - quay.io/argoproj/argo-rollouts:v1.8.3 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.80 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.28.0 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/edoburu/pgbouncer:v1.24.0-p0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.2.6-alpine - quay.io/akuity/rancher/k3s:v1.33.5-k3s1 - quay.io/akuity/redis:7.2.11-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - quay.io/argoproj/argo-rollouts:v1.8.3 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.80 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.27.0 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/edoburu/pgbouncer:v1.24.0-p0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.2.6-alpine - quay.io/akuity/rancher/k3s:v1.33.5-k3s1 - quay.io/akuity/redis:7.2.11-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.75 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.26.2 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/edoburu/pgbouncer:v1.24.0-p0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.2.6-alpine - quay.io/akuity/rancher/k3s:v1.33.5-k3s1 - quay.io/akuity/redis:7.2.11-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.72 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.26.1 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/edoburu/pgbouncer:v1.24.0-p0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.2.6-alpine - quay.io/akuity/rancher/k3s:v1.33.5-k3s1 - quay.io/akuity/redis:7.2.10-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.71 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.25.0 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/edoburu/pgbouncer:v1.24.0-p0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.0.5-alpine - quay.io/akuity/rancher/k3s:v1.32.3-k3s1 - quay.io/akuity/redis:7.2.10-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.64 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.24.1 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/edoburu/pgbouncer:v1.24.0-p0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.0.5-alpine - quay.io/akuity/rancher/k3s:v1.32.3-k3s1 - quay.io/akuity/redis:7.0.14-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.61 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.23.3 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/edoburu/pgbouncer:v1.24.0-p0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.0.5-alpine - quay.io/akuity/rancher/k3s:v1.32.3-k3s1 - quay.io/akuity/redis:7.0.14-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.59 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.23.2 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/edoburu/pgbouncer:v1.24.0-p0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.0.5-alpine - quay.io/akuity/rancher/k3s:v1.32.3-k3s1 - quay.io/akuity/redis:7.0.14-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.59 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.23.1 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/edoburu/pgbouncer:v1.24.0-p0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.0.5-alpine - quay.io/akuity/rancher/k3s:v1.32.3-k3s1 - quay.io/akuity/redis:7.0.14-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.59 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.23.0 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/edoburu/pgbouncer:v1.24.0-p0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.0.5-alpine - quay.io/akuity/rancher/k3s:v1.32.3-k3s1 - quay.io/akuity/redis:7.0.14-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.59 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.22.2 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/edoburu/pgbouncer:v1.24.0-p0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.0.5-alpine - quay.io/akuity/rancher/k3s:v1.32.3-k3s1 - quay.io/akuity/redis:7.0.14-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.58 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.22.1 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/edoburu/pgbouncer:v1.24.0-p0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.0.5-alpine - quay.io/akuity/rancher/k3s:v1.32.3-k3s1 - quay.io/akuity/redis:7.0.14-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.58 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.22.0 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.0.5-alpine - quay.io/akuity/pgbouncer:v1.24.0-p0 - quay.io/akuity/rancher/k3s:v1.30.8-k3s1 - quay.io/akuity/redis:7.0.14-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.57 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.21.5 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.0.5-alpine - quay.io/akuity/pgbouncer:v1.24.0-p0 - quay.io/akuity/rancher/k3s:v1.30.8-k3s1 - quay.io/akuity/redis:7.0.14-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.57 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.21.4 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.0.5-alpine - quay.io/akuity/pgbouncer:v1.24.0-p0 - quay.io/akuity/rancher/k3s:v1.30.8-k3s1 - quay.io/akuity/redis:7.0.14-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.56 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.21.3 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.0.5-alpine - quay.io/akuity/pgbouncer:v1.24.0-p0 - quay.io/akuity/rancher/k3s:v1.30.8-k3s1 - quay.io/akuity/redis:7.0.14-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.55 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.21.2 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/pgbouncer:v1.24.0-p0 - quay.io/akuity/rancher/k3s:v1.30.8-k3s1 - quay.io/akuity/redis:7.0.14-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.54 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.21.1 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.0.5-alpine - quay.io/akuity/pgbouncer:v1.24.0-p0 - quay.io/akuity/rancher/k3s:v1.30.8-k3s1 - quay.io/akuity/redis:7.0.14-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.54 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.21.0 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/pgbouncer:v1.24.0-p0 - quay.io/akuity/rancher/k3s:v1.30.8-k3s1 - quay.io/akuity/redis:7.0.14-alpine - quay.io/akuity/haproxy:3.0.5-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.54 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.20.1 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.0.5-alpine - quay.io/akuity/rancher/k3s:v1.30.8-k3s1 - quay.io/akuity/redis:7.0.14-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.54 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.20.0 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.0.5-alpine - quay.io/akuity/rancher/k3s:v1.30.8-k3s1 - quay.io/akuity/redis:7.0.14-alpine - quay.io/argoproj/argo-rollouts:v1.7.2 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.53 - us-docker.pkg.dev/akuity/docker-io/curlimages/curl:8.11.1 ### v0.19.1 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.0.5-alpine - quay.io/akuity/rancher/k3s:v1.30.5-k3s1 - quay.io/akuity/redis:7.0.14-alpine - quay.io/akuityio/argo-rollouts:v1.6.5-ak.3 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.49 ### v0.19.0 - ghcr.io/dexidp/dex:v2.37.0 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/ghcr.io/appscode-images/pgpool2:4.5.3 - quay.io/akuity/haproxy:3.0.5-alpine - quay.io/akuity/rancher/k3s:v1.30.5-k3s1 - quay.io/akuity/redis:7.0.14-alpine - quay.io/akuityio/argo-rollouts:v1.6.5-ak.3 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.49 ### v0.18.0 - ghcr.io/dexidp/dex:v2.37.0 - pgpool/pgpool:4.3.1 - quay.io/akuity/busybox:1.36.0 - quay.io/akuity/dexidp/dex:v2.38.0 - quay.io/akuity/haproxy:3.0.5-alpine - quay.io/akuity/rancher/k3s:v1.28.14-k3s1 - quay.io/akuity/redis:7.0.14-alpine - quay.io/akuityio/argo-rollouts:v1.6.5-ak.3 - us-docker.pkg.dev/akuity/akp-sh/agent-server:0.5.47 --- ## Helm Values Reference This page contains the reference for all the Helm values options available in the Self Hosted Akuity Platform. ## Parameters ### License Key | Name | Description | Value | | ------------ | ----------- | ----- | | `licenseKey` | | `""` | ### Image Parameters | Name | Description | Value | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | `image.repository` | Image repository of the Akuity Platform | `us-docker.pkg.dev/akuity/akp-sh/akuity-platform` | | `image.tag` | Overrides the image tag (default is the chart version) | `""` | | `image.secret.enabled` | Reference the 'akuity-pullsecrets' image pull secret from platform workloads. Disable when images are pulled without a secret (e.g. node IRSA for ECR). | `true` | | `image.secret.create` | Creates the 'akuity-pullsecrets' secret. Set to false when the secret is provided externally (e.g. via External Secrets Operator). | `true` | | `image.username` | Username to the Akuity Platform container registry | `_json_key_base64` | | `image.password` | Password to the Akuity Platform container registry | `""` | | `image.argocd.host` | Overrides the Argo CD image host | `""` | | `image.argocd.repo` | Overrides the Argo CD image repository | `""` | | `image.agentServer.host` | Overrides the agent server image host. If not set, the host | `nil` | ### Portal Parameters | Name | Description | Value | | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | | `portal.url` | Public URL to portal (e.g. `https://akuity.example.com`) | `""` | | `portal.imagePullPolicy` | Portal server image pull policy | `Always` | | `portal.debug` | Enable debug logging on the portal server. Only enable in production for debugging purposes. | `false` | | `portal.maxEmailInvitationsPerBatch` | Maximum number of invitation emails which can be sent in one go | `5` | | `portal.autoscaling.enabled` | Enables horizontal pod autoscaling for the portal server | `true` | | `portal.autoscaling.minReplicas` | Sets the minimum number of replicas | `3` | | `portal.autoscaling.maxReplicas` | Sets the maximum number of replicas | `10` | | `portal.autoscaling.targetCPUUtilizationPercentage` | Sets the target CPU utilization percentage | `80` | | `portal.autoscaling.targetMemoryUtilizationPercentage` | Sets the target memory utilization percentage | `80` | | `portal.seed.organization.name` | Creates an organization with a given name | `nil` | | `portal.seed.organization.owner` | Creates an owner for the given organization with the given e-mail address. | `nil` | | `portal.seed.organization.apiKey.create` | If set to true, generates an api key for the given organization. | `nil` | | `portal.seed.organization.apiKey.description` | Sets the description for the API Key. | `nil` | | `portal.seed.organization.apiKey.role` | Can be set to organization/owner (default), organization/admin or organization/member | `nil` | | `portal.seed.organization.apiKey.expiryIn` | A valid interval string (e.g 1d, 2w, 6h) or 0 (default) for no expiry. | `nil` | | `portal.seed.organization.apiKey.outputFormat` | Can be set to wide (default) or json | `nil` | | `portal.seed.organization.apiKey.recreate` | Recreate the key if it already exists (default: false) | `nil` | | `portal.resources` | Resources limits and requests for the portal server containers | `{}` | | `portal.tolerations` | Tolerations for the portal-server pod | `[]` | | `portal.serviceAccount.annotations` | Annotations for the portal-server service account | `{}` | | `portal.env` | Additional environment variables added to the portal server | `{}` | | `portal.env.OTEL_SDK_DISABLED` | Disables the OpenTelemetry SDK. Defaults to `"true"` (no traces exported). Set to `"false"` and configure the standard `OTEL_TRACES_EXPORTER` / `OTEL_EXPORTER_OTLP_*` variables to export traces to an OTLP collector. | `true` | | `portal.env.OTEL_SERVICE_NAME` | Sets the OpenTelemetry `service.name` resource attribute reported on this component's traces. | `portal-server` | | `portal.env.MIN_ORGANIZATION_NAME_LENGTH` | The minimum length of an organization name that is allowed on the platform, minimum value is `2`, defaults to `4` if undefined | `nil` | | `portal.env.MIN_CLUSTER_NAME_LENGTH` | The minimum length of a cluster name that is allowed on the platform, minimum value is `2`, defaults to `3` if undefined | `nil` | | `portal.env.MIN_INSTANCE_NAME_LENGTH` | The minimum length of an Argo CD instance name that is allowed on the platform, minimum value is `2`, defaults to `3` if undefined | `nil` | | `portal.topologySpreadConstraints` | Sets topology spread constraints for the portal server deployment | `nil` | ### Platform controller Parameters | Name | Description | Value | | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `platformController.imagePullPolicy` | Platform controller image pull policy | `Always` | | `platformController.debug` | Enable debug logging on the platform controller. Only enable in production for debugging purposes. | `false` | | `platformController.domainSuffix` | Platform controller domain suffix to use (defaults to hostname of `.portal.url`) | `""` | | `platformController.instanceSubDomains` | Enables using nested subdomains for managed argocd/kargo instances | `true` | | `platformController.overrideDefaultDomains` | Enables setting subdomains for k3s, agent server etc. or setting the FQDN as a suffix for those services. | `false` | | `platformController.userProvidedArgoCDVersions` | Enables setting extra Argo CD _patch_ versions. This is useful if an Argo CD version has been released (e.g a critical bugfix or a CVE) that is not present in the current version of the Akuity Platform. | `[]` | | `platformController.tolerations` | Tolerations for the platform controller pod | `[]` | | `platformController.serviceAccount.annotations` | Annotations for the platform controller service account | `{}` | ### Resources limits and requests for the platform controller containers | Name | Description | Value | | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | | `platformController.env` | Adds additional environment variables to the platform controller configmap | `{}` | | `platformController.env.OTEL_SDK_DISABLED` | Disables the OpenTelemetry SDK. Defaults to `"true"` (no traces exported). Set to `"false"` and configure the standard `OTEL_TRACES_EXPORTER` / `OTEL_EXPORTER_OTLP_*` variables to export traces to an OTLP collector. | `true` | | `platformController.env.OTEL_SERVICE_NAME` | Sets the OpenTelemetry `service.name` resource attribute reported on this component's traces. | `platform-controller` | | `platformController.env.ARGOCD_APP_RESYNC_INTERVAL_SECONDS` | Argo CD Application resync interval in seconds (if `0` or undefined then Argo CD built-in default is used) | `nil` | | `platformController.env.AGENT_STATUS_UPDATE_INTERVAL_SECONDS` | Agent status update interval in seconds (if `0` or undefined then Agent built-in default is used) | `nil` | | `platformController.env.SHARED_K3S_DB_CONNECTION_AUTH` | Set to `true` for all tenants to use database.user and database.password credentials rather than a personal credentials for each tenant. This might be needed when connecting to the database through RDS Proxy which has a limit of 200 users | `nil` | | `platformController.commonAgentCert` | common agent cert provides the shared certificate for both *.cdsvcs.akuity.example.com as well as *.kargosvcs.akuity.example.com domains used by agents | `""` | | `platformController.argocdAgentCert` | argocd agent cert provides the certificate for only *.cdsvcs.akuity.example.com used by argocd agents | `""` | | `platformController.kargoAgentCert` | kargo agent cert provides the certificate for only *.kargosvcs.akuity.example.com domains used by kargo agents | `""` | ### Notification controller Parameters | Name | Description | Value | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | | `notificationController.enabled` | Enabled the notification controller | `false` | | `notificationController.imagePullPolicy` | Notification controller image pull policy | `Always` | | `notificationController.debug` | Enable debug logging on the notification controller. Only enable in production for debugging purposes. | `false` | | `notificationController.tolerations` | Tolerations for the notification controller pod | `[]` | | `notificationController.serviceAccount.annotations` | Annotations for the notification controller service account | `{}` | | `notificationController.resources` | Resources limits and requests for the notification controller containers | `{}` | | `notificationController.env` | Adds additional environment variables to the notification controller configmap | `{}` | | `notificationController.env.OTEL_SDK_DISABLED` | Disables the OpenTelemetry SDK. Defaults to `"true"` (no traces exported). Set to `"false"` and configure the standard `OTEL_TRACES_EXPORTER` / `OTEL_EXPORTER_OTLP_*` variables to export traces to an OTLP collector. | `true` | | `notificationController.env.OTEL_SERVICE_NAME` | Sets the OpenTelemetry `service.name` resource attribute reported on this component's traces. | `notification-controller` | | `addonController.enabled` | Enabled the addon controller | `true` | | `addonController.imagePullPolicy` | Notification controller image pull policy | `Always` | | `addonController.debug` | Enable debug logging on the addon controller. Only enable in production for debugging purposes. | `false` | | `addonController.tolerations` | Tolerations for the addon controller pod | `[]` | | `addonController.serviceAccount.annotations` | Annotations for the addon controller service account | `{}` | | `addonController.resources` | Resources limits and requests for the addon controller containers | `{}` | | `addonController.env` | Adds additional environment variables to the addon controller configmap | `{}` | | `addonController.env.OTEL_SDK_DISABLED` | Disables the OpenTelemetry SDK. Defaults to `"true"` (no traces exported). Set to `"false"` and configure the standard `OTEL_TRACES_EXPORTER` / `OTEL_EXPORTER_OTLP_*` variables to export traces to an OTLP collector. | `true` | | `addonController.env.OTEL_SERVICE_NAME` | Sets the OpenTelemetry `service.name` resource attribute reported on this component's traces. | `addon-controller` | ### Secret Parameters | Name | Description | Value | | --------------- | ------------------------------------ | ------ | | `secret.create` | Creates the 'akuity-platform' Secret | `true` | ### TLS Parameters TLS configuration for ingress. These details are used for configuring Traefik with the proper certificates. | Name | Description | Value | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | | `tls.terminationEnabled` | Enable TLS for the Akuity Platform. TLS can be disabled to allow for SSL termination to be handled by a load balancer or other proxy/ingress before it reaches the Akuity Platform | `true` | | `tls.secret.create` | Creates the 'akuity-platform-tls' Secret used as the Traefik default certificate. Set to false if creating the secret in another way (e.g. cert-manager) | `true` | | `tls.crt` | TLS certificate. Can be valid for multiple domains (e.g. https://akuity.example.com, https://\*.cd.akuity.example.com, https://\*.cdsvcs.akuity.example.com) | `""` | | `tls.key` | TLS private key | `""` | | `tls.additionalCertificates` | List of additional TLS certificates to serve in the form of Kubernetes Secrets. This may be necessary if different certificates are used for different domains (e.g. https://akuity.example.com, https://\*.cd.akuity.example.com, https://\*.cdsvcs.akuity.example.com) | `[]` | ### Database Parameters | Name | Description | Value | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `database.host` | Database hostname | `""` | | `database.port` | Database port | `5432` | | `database.user` | Database username | `""` | | `database.password` | Database password | `""` | | `database.dbname` | Database name | `postgres` | | `database.schemaname` | Schema name | `public` | | `database.createSchema` | create schema automatically | `false` | | `database.dataKey` | 256-bit base64 encoded encryption key used for envelope encryption of sensitive data columns. A random key can be generated with the following command: `openssl rand -base64 32`. NOTE: loss of this key will result in permanent and irrevocable data loss! | `""` | | `database.readOnlyHost` | Database read-only hostname. Used for connection load balancing of read requests to read-only database replicas. If omitted, will default to the write hostname. | `""` | | `database.sslmode` | Database SSL mode | `require` | ### Password Policy Parameters Password complexity policy applied to all platform-generated passwords (tenant Postgres users, Redis instance passwords, and agent passwords). Each field is optional — leave it unset to keep the platform default (a 21-character mixed-case alphanumeric password including special characters). These overrides exist primarily for self-hosted deployments whose database engine (e.g. GCP Cloud SQL with `password_validation_policy`) enforces a stricter or different policy than the platform default. | Name | Description | Value | | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | `passwordPolicy.length` | Length of generated passwords. Leave unset (or 0) to use the platform default of 21 characters. Must be at least as large as the number of enabled character classes. | `nil` | | `passwordPolicy.useSpecialChars` | Whether to include non-alphanumeric characters in generated passwords. Set to `false` if the target database rejects passwords containing special characters; set to `true` if the database requires at least one special character. Leave unset to use the platform default (`true`). | `nil` | | `passwordPolicy.useNumbers` | Whether to include digits in generated passwords. Leave unset to use the platform default (`true`). | `nil` | | `passwordPolicy.useUppercase` | Whether to include uppercase letters in generated passwords. Leave unset to use the platform default (`true`). | `nil` | | `passwordPolicy.useLowercase` | Whether to include lowercase letters in generated passwords. Leave unset to use the platform default (`true`). | `nil` | ### SSO Parameters Single Sign-On configuration. Either OIDC or auth0 must be configured. | Name | Description | Value | | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | | `sso.oidc.enabled` | Enable OIDC authentication | `true` | | `sso.oidc.issuer` | OIDC issuer URL. This value is ignored if dex is enabled and served as a subpath | `""` | | `sso.oidc.clientID` | OIDC client ID. If dex is enabled, value will be used as Dex's client ID | `""` | | `sso.oidc.clientSecret` | OIDC client secret. If dex is enabled, value will be used as Dex's client secret | `""` | | `sso.oidc.scopes` | OIDC scopes to request (default: openid,profile,email,offline_access) | `openid,profile,email,offline_access` | | `sso.oidc.logoutURL` | OIDC logout url | `""` | | `sso.oidc.insecureSkipTLSVerify` | Skip TLS verification of the OIDC provider. This will be needed if dex is served as a subpath, and TLS is not yet configured. | `false` | | `sso.auth0.enabled` | Enable Auth0 configuration | `false` | | `sso.auth0.domain` | Auth0 domain (e.g. example.us.auth0.com) | `""` | | `sso.auth0.audience` | Auth0 Audience of the token | `""` | | `sso.auth0.clientID` | Auth0 client id for portal service | `nil` | | `sso.auth0.cliClientID` | Auth0 client id for CLI | `nil` | | `sso.dex.enabled` | Install dex | `false` | | `sso.dex.image.repository` | Image repository for Dex | `ghcr.io/dexidp/dex` | | `sso.dex.image.tag` | Overrides the Dex image tag | `v2.35.3` | | `sso.dex.image.secret.create` | Creates the 'dex-pullsecrets' secret | `false` | | `sso.dex.image.username` | Username for the Dex container registry | `""` | | `sso.dex.image.password` | Password for the Dex container registry | `""` | | `sso.dex.tolerations` | Tolerations for the Dex pod | `[]` | | `sso.dex.imagePullSecrets` | Image pull secrets for Dex | `[]` | | `sso.dex.serviceAccount.annotations` | Annotations for the Dex service account | `{}` | | `sso.dex.secret.create` | Creates the 'dex' Secret whose data values will be mounted as environment variables to the Dex Deployment | `true` | | `sso.dex.secret.data` | Secret data keys and plain-text values to set in the 'dex' Secret. These will be environment variables to dex so they can be referenced in the dex/config.yaml | `{}` | | `sso.dex.resources` | Resources limits and requests for the Dex containers | `{}` | | `sso.dex.issuerSubPath` | Serve dex as a subpath of the portal URL (e.g. https://akuity.example.com/dex) | `true` | | `sso.dex.ingress.enabled` | Enable ingress to dex | `false` | | `sso.dex.ingress.host` | Host value to dex ingress | `""` | | `sso.dex.config` | Additional dex/config.yaml configuration. See https://dexidp.io/docs/ for dex documentation. Configuration can reference environment variables in the 'dex' Secret (e.g. $MICROSOFT_CLIENT_SECRET) | `{}` | | `sso.roleFromGroups` | Contains the SSO groups that will be automatically assigned roles | `nil` | | `sso.roleFromGroups.member` | Comma separated list of SSO groups that will be assigned the 'member' role | `""` | | `sso.roleFromGroups.admin` | Comma separated list of SSO groups that will be assigned the 'admin' role | `""` | | `sso.roleFromGroups.owner` | Comma separated list of SSO groups that will be assigned the 'owner' role | `""` | | `sso.roleTeamFromGroups` | Contains the slice of SSO groups with org and team mapping | `nil` | | `sso.roleTeamFromGroups.oidcGroup` | SSO group name | `nil` | | `sso.roleTeamFromGroups.orgRole` | org role(`member` or `owner`) | `nil` | | `sso.roleTeamFromGroups.teams` | slice of teams to be assigned | `nil` | | `sso.roleTeamFromGroups.teams.name` | name of the team | `nil` | ### Traefik Parameters Traefik is a required component of the Akuity Platform. The Akuity Platform expects a `traefik-external` ingress class to be present and is installed with Traefik in this section. | Name | Description | Value | | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | `traefik.enabled` | Install Traefik | `true` | | `traefik.service.annotations` | Annotations for the Traefik service. CAUTION: This has the potential to override annotations set by `aws.enabled` or `compatibility.ipv6`! | `{}` | | `traefik.service.loadBalancerClass` | Allows for setting the load balancer class. By default this is empty. NOTE: once set, this cannot be changed without destroying and recreating the service | `nil` | | `traefik.tolerations` | Tolerations for the Traefik pod | `[]` | | `traefik.imagePullSecrets` | Extra/optional image pull secrets for Traefik | `[]` | | `traefik.serviceAccount.annotations` | Annotations for the Traefik service account | `{}` | | `traefik.image.repository` | Image repository for Traefik | `public.ecr.aws/docker/library/traefik` | | `traefik.image.tag` | Overrides the Traefik image tag | `v3.3.6` | | `traefik.image.secret.create` | Creates the 'traefik-pullsecrets' secret | `false` | | `traefik.image.username` | Username for the Traefik container registry | `""` | | `traefik.image.password` | Password for the Traefik container registry | `""` | | `traefik.crd.enabled` | Install Traefik CRDs | `true` | | `traefik.websecureRedirect` | Redirect 80 to 443. Only set this to false for testing purposes | `true` | | `traefik.forceLoadBalancer` | Forces the traefik service to be of type LoadBalancer. By default, if tls.terminationEnabled is true, the service will be of type LoadBalancer. If tls.terminationEnabled is false, the service will be of type ClusterIP. This allows you to override the default behavior and force the service to be of type LoadBalancer. | `false` | | `traefik.autoscaling.enabled` | Enables horizontal pod autoscaling for Traefik | `true` | | `traefik.autoscaling.minReplicas` | Sets the minimum number of replicas | `3` | | `traefik.autoscaling.maxReplicas` | Sets the maximum number of replicas | `20` | | `traefik.autoscaling.targetCPUUtilizationPercentage` | Sets the target CPU utilization percentage | `80` | | `traefik.autoscaling.targetMemoryUtilizationPercentage` | Sets the target memory utilization percentage | `80` | | `traefik.replicas` | If autoscaling is not enabled, the number of replicas for the Traefik deployment | `1` | | `traefik.resources` | Resources limits and requests for the Traefik containers | `{}` | | `traefik.topologySpreadConstraints` | Sets topology spread constraints for the Traefik deployment | `nil` | ### Other Parameters | Name | Description | Value | | ----------------------------- | ---------------------------------------------------- | ------- | | `agent.insecureSkipTLSVerify` | Skip TLS verification from agents to Akuity Platform | `false` | | `aws.enabled` | Add AWS specific annotations to resources | `true` | ### Kargo Instance Parameters | Name | Description | Value | | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | | `kargoInstanceValues.k3s.etcd_compaction_interval` | Interval at which the kube-apiserver triggers Kine compaction. Lower values compact more frequently but increase database load. Only adjust after investigating database performance, instance resource limits, and workload. | `5m` | | `kargoInstanceValues.k3s.kine_compact_timeout` | Maximum time allowed for a single compaction transaction. Only adjust after investigating database performance, instance resource limits, and workload. | `5s` | | `kargoInstanceValues.k3s.kine_compact_batch_size` | Number of revisions to compact per batch. Smaller batches reduce per-transaction load but may take more cycles to catch up. Only adjust after investigating database performance, instance resource limits, and workload. | `1000` | ### Argo CD Instance Parameters | Name | Description | Value | | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | | `instanceValues.k3s.etcd_compaction_interval` | Interval at which the kube-apiserver triggers Kine compaction. Lower values compact more frequently but increase database load. Only adjust after investigating database performance, instance resource limits, and workload. | `5m` | | `instanceValues.k3s.kine_compact_timeout` | Maximum time allowed for a single compaction transaction. Only adjust after investigating database performance, instance resource limits, and workload. | `5s` | | `instanceValues.k3s.kine_compact_batch_size` | Number of revisions to compact per batch. Smaller batches reduce per-transaction load but may take more cycles to catch up. Only adjust after investigating database performance, instance resource limits, and workload. | `1000` | | `instanceValues.kustomization` | Kustomizations to be applied to Argo CD instances | `nil` | | `instanceValues.k3s_proxy` | k3s proxy parameters | `nil` | | `instanceValues.pgpool` | pgpool parameters | `nil` | | `smtp.host` | SMTP host | `""` | | `smtp.port` | SMTP port | `587` | | `smtp.user` | SMTP username | `""` | | `smtp.password` | SMTP password | `""` | | `liquibase.image.repository` | Image repository for Liquibase | `quay.io/akuity/liquibase` | | `liquibase.image.tag` | Overrides the Liquibase image tag | `4.32` | | `liquibase.image.secret.create` | Creates the 'liquibase-pullsecrets' secret | `false` | | `liquibase.image.username` | Username for the Liquibase container registry | `""` | | `liquibase.image.password` | Password for the Liquibase container registry | `""` | ### Dragonflydb Dragonflydb Operator is used to deploy and manage Dragonfly instances, this should only be enabled for experimental purposes. | Name | Description | Value | | ---------------------------- | ------------------------------------------------------------------------------ | ------- | | `dragonflydb.enabled` | Installs the Dragonfly operator. | `false` | | `dragonflydb.replicas` | The number of replicas for the Dragonfly deployment | `2` | | `dragonflydb.resources` | Resources limits and requests for the Dragonfly operator containers | `{}` | | `dragonflydb.serviceMonitor` | When set true then use a ServiceMonitor to configure scraping for the operator | `false` | ### Instance Upgrader Parameters Instance Upgrader is a job that upgrades managed instances during Akuity Platform upgrade. | Name | Description | Value | | -------------------------- | --------------------------------- | ------ | | `instanceUpgrader.enabled` | Enables the instance upgrader job | `true` | ### Compatibility Specify which compatibility modes will be required | Name | Description | Value | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | | `compatibility.openshift` | Enables Openshift compatibility. This option will modify platform install manifests, Argo CD instance manifests, and Kargo instance manifests to support running on Openshift. | `false` | | `compatibility.sidecarContainers` | enables use of the Kubernetes sidecar containers feature in the platform workloads | `true` | | `compatibility.ipv6Only` | Enables IPv6 only compatibility | `false` | ### Callhome Parameters Callhome periodically uploads a telemetry bundle to Akuity for usage tracking. | Name | Description | Value | | -------------------------- | ---------------------------------------------------- | --------------------------------------- | | `callhome.enabled` | Enable the callhome CronJob | `true` | | `callhome.schedule` | Cron schedule (default: weekly on Sunday at 2am UTC) | `0 2 * * 0` | | `callhome.uploadUrl` | Akuity callhome upload endpoint | `https://telemetry-us.akuity.io/upload` | | `callhome.imagePullPolicy` | Image pull policy | `IfNotPresent` | | `callhome.resources` | Resource requests/limits | `{}` | ### Log Cleanup Parameters Log Cleaner is a cron job that cleans up old logs stored from the database. These logs can be from different tasks like kargo analysis jobs etc. | Name | Description | Value | | ---------------------------- | ---------------------------------------------------------------------------------------------- | ----------- | | `logCleaner.enabled` | Enables the log cleaner job | `false` | | `logCleaner.dryRun` | Enables dry run mode for the log cleaner job, when enabled the entries aren't deleted | `false` | | `logCleaner.debug` | Enable debug logging on the log cleaner job. Only enable in production for debugging purposes. | `false` | | `logCleaner.imagePullPolicy` | image pull policy for the log cleaner | `Always` | | `logCleaner.schedule` | Cron schedule for the log cleaner job | `0 0 * * *` | | `logCleaner.resources` | Resources limits and requests for the log cleaner job | `{}` | ### Event Cleaner Parameters Event Cleaner is a cron job that batch-deletes events older than a configurable retention window from the portal database. | Name | Description | Value | | ------------------------------ | ------------------------------------------------------------------------------------------------ | ----------- | | `eventCleaner.enabled` | Enables the event cleaner job | `true` | | `eventCleaner.dryRun` | Enables dry run mode for the event cleaner job, when enabled the entries aren't deleted | `false` | | `eventCleaner.debug` | Enable debug logging on the event cleaner job. Only enable in production for debugging purposes. | `false` | | `eventCleaner.imagePullPolicy` | image pull policy for the event cleaner | `Always` | | `eventCleaner.schedule` | Cron schedule for the event cleaner job | `0 0 * * *` | | `eventCleaner.batchSize` | Number of rows to delete per batch | `10000` | | `eventCleaner.retentionDays` | Delete events older than this many days | `90` | | `eventCleaner.resources` | Resources limits and requests for the event cleaner job | `{}` | ### Akuity Intelligence Parameters Akuity Intelligence is an optional component that provides advanced insights and recommendations for your Kubernetes clusters. | Name | Description | Value | | -------------------------------------- | -------------------------------------------------------------------------------- | ----- | | `intelligence.openAI.baseURL` | base URL for OpenAI API compatible endpoints (default https://api.openai.com/v1) | `""` | | `intelligence.openAI.mainModel` | main model used by AI Agent (e.g. gpt-4.1) | `""` | | `intelligence.openAI.searchModel` | model with search capabilities (e.g. gpt-4o-mini-search-preview) | `""` | | `intelligence.openAI.lightweightModel` | lightweight model for non-critical tasks (e.g. gpt-4.1-nano) | `""` | | `intelligence.openAI.apiKey` | OpenAI API key for Akuity Intelligence features | `""` | | `intelligence.anthropic.apiKey` | Anthropic API key for Akuity Intelligence features | `""` | | `intelligence.gemini.apiKey` | Gemini API key (Google AI Studio) for Akuity Intelligence features | `""` | ### LiteLLM Parameters LiteLLM is a proxy server for LLM providers. | Name | Description | Value | | ------------------------------------------------------- | -------------------------------------------------- | ------------------------ | | `litellm.image.repository` | Image repository for LiteLLM | `quay.io/akuity/litellm` | | `litellm.image.tag` | LiteLLM image tag | `v1.90.0` | | `litellm.autoscaling.enabled` | Enables horizontal pod autoscaling for LiteLLM | `true` | | `litellm.autoscaling.minReplicas` | Sets the minimum number of replicas | `2` | | `litellm.autoscaling.maxReplicas` | Sets the maximum number of replicas | `3` | | `litellm.autoscaling.targetCPUUtilizationPercentage` | Sets the target CPU utilization percentage | `80` | | `litellm.autoscaling.targetMemoryUtilizationPercentage` | Sets the target memory utilization percentage | `80` | | `litellm.replicas` | If autoscaling is disabled, the number of replicas | `1` | ### Monitoring Parameters Monitoring integration with the Prometheus Operator and Grafana. When enabled, the chart deploys ServiceMonitors and PodMonitors for scraping, a PrometheusRule with bundled alerts, a Grafana dashboard ConfigMap, and a Grafana PostgreSQL datasource Secret used by the dashboard's portal-DB-backed panels. Disabled by default. See the Monitoring guide at https://docs.akuity.io/self-hosted/monitoring for the full setup, verification, and operations reference. | Name | Description | Value | | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- | | `monitoring.enabled` | Enable monitoring integration (ServiceMonitors, PodMonitors, PrometheusRule, Grafana dashboard, Grafana datasource) | `false` | | `monitoring.serviceMonitors.enabled` | Deploy ServiceMonitors for platform components | `true` | | `monitoring.serviceMonitors.interval` | Prometheus scrape interval | `60s` | | `monitoring.serviceMonitors.scrapeTimeout` | Prometheus scrape timeout (if empty, Prometheus uses the global scrape timeout) | `""` | | `monitoring.serviceMonitors.additionalLabels.release` | Label that satisfies kube-prometheus-stack's default `serviceMonitorSelector` so Prometheus discovers these ServiceMonitors out of the box. Set to your kube-prometheus-stack Helm release name if it differs. You can add more labels to this map as needed. | `kube-prometheus-stack` | | `monitoring.serviceMonitors.annotations` | Annotations on ServiceMonitor resources | `{}` | | `monitoring.serviceMonitors.namespace` | Namespace to deploy ServiceMonitors into (defaults to release namespace) | `""` | | `monitoring.serviceMonitors.relabelings` | Prometheus relabel configs applied before scraping | `[]` | | `monitoring.serviceMonitors.metricRelabelings` | Prometheus relabel configs applied to scraped samples before ingestion | `[]` | | `monitoring.serviceMonitors.honorLabels` | When true, preserves the metric's labels when they collide with the target's labels | `false` | | `monitoring.podMonitors.enabled` | Deploy PodMonitors that scrape repo-server-delegate and repo-server-proxy metrics from instance namespaces. These only produce data when an instance uses the Repo Server Delegate feature; leaving them enabled when no instance uses it is safe and has no cost. | `true` | | `monitoring.podMonitors.interval` | Prometheus scrape interval | `60s` | | `monitoring.podMonitors.scrapeTimeout` | Prometheus scrape timeout (if empty, Prometheus uses the global scrape timeout) | `""` | | `monitoring.podMonitors.additionalLabels.release` | Label that satisfies kube-prometheus-stack's default `podMonitorSelector` so Prometheus discovers these PodMonitors out of the box. Set to your kube-prometheus-stack Helm release name if it differs. You can add more labels to this map as needed. | `kube-prometheus-stack` | | `monitoring.podMonitors.annotations` | Annotations on PodMonitor resources | `{}` | | `monitoring.podMonitors.namespace` | Namespace to deploy PodMonitors into (defaults to release namespace) | `""` | | `monitoring.podMonitors.relabelings` | Prometheus relabel configs applied before scraping | `[]` | | `monitoring.podMonitors.metricRelabelings` | Prometheus relabel configs applied to scraped samples before ingestion | `[]` | | `monitoring.podMonitors.honorLabels` | When true, preserves the metric's labels when they collide with the target's labels | `false` | | `monitoring.prometheusRules.enabled` | Deploy PrometheusRule alert definitions | `true` | | `monitoring.prometheusRules.additionalLabels.release` | Label that satisfies kube-prometheus-stack's default `ruleSelector` so Prometheus loads these alert rules out of the box. Set to your kube-prometheus-stack Helm release name if it differs. You can add more labels to this map as needed. | `kube-prometheus-stack` | | `monitoring.prometheusRules.annotations` | Annotations on the PrometheusRule resource | `{}` | | `monitoring.prometheusRules.namespace` | Namespace to deploy the PrometheusRule into (defaults to release namespace) | `""` | | `monitoring.prometheusRules.additionalRules` | Additional user-defined Prometheus alerting or recording rules appended to the bundled rule groups. Entries follow the standard PrometheusRule rule schema (`alert`, `expr`, `for`, `labels`, `annotations`, or `record` + `expr`). | `[]` | | `monitoring.grafanaDashboard.enabled` | Deploy the Akuity Platform Grafana dashboard as a ConfigMap | `true` | | `monitoring.grafanaDashboard.namespace` | Namespace to deploy the dashboard ConfigMap into (defaults to release namespace) | `""` | | `monitoring.grafanaDashboard.additionalLabels` | Additional labels on the dashboard ConfigMap | `{}` | | `monitoring.grafanaDashboard.label` | Label key that the Grafana sidecar watches to discover dashboard ConfigMaps. Must match the Grafana sidecar's configured `dashboards.label`. | `grafana_dashboard` | | `monitoring.grafanaDashboard.labelValue` | Value for the Grafana sidecar discovery label. Must match the Grafana sidecar's configured `dashboards.labelValue` (empty string matches any value). | `1` | | `monitoring.grafanaDashboard.annotations` | Annotations on the dashboard ConfigMap | `{}` | | `monitoring.grafanaDashboard.folder` | Grafana folder to place the dashboard in. Applied via the `grafana_folder` annotation on the dashboard ConfigMap; the Grafana dashboard sidecar must be configured with `folderAnnotation: grafana_folder` for this to take effect. Leave empty to use the sidecar's default folder. | `""` | | `monitoring.grafanaDatasource.enabled` | Provision a Grafana PostgreSQL datasource for portal DB-backed panels | `true` | | `monitoring.grafanaDatasource.namespace` | Namespace to deploy the datasource Secret into (defaults to grafanaDashboard.namespace or release namespace) | `""` | | `monitoring.grafanaDatasource.additionalLabels` | Additional labels on the datasource Secret | `{}` | | `monitoring.grafanaDatasource.label` | Label key that the Grafana datasource sidecar watches to discover datasource Secrets. Must match the Grafana sidecar's configured `datasources.label`. | `grafana_datasource` | | `monitoring.grafanaDatasource.labelValue` | Value for the Grafana datasource sidecar discovery label. Must match the Grafana sidecar's configured `datasources.labelValue` (empty string matches any value). | `1` | | `monitoring.grafanaDatasource.annotations` | Annotations on the datasource Secret | `{}` | | `monitoring.grafanaDatasource.datasourceName` | Grafana datasource name shown in the Grafana UI. When empty, defaults to the Helm release name followed by ` Portal DB` (for example, `akuity Portal DB`). Dashboard panels look up the datasource by UID, not by name, so changing this does not break the bundled dashboard. | `""` | | `monitoring.grafanaDatasource.datasourceUID` | Grafana datasource UID referenced by dashboard panels. When empty, defaults to the Helm release name followed by `-portal-db` (for example, `akuity-portal-db`). If overridden, update the dashboard's datasource UIDs to match or panels will not load data. | `""` | | `monitoring.grafanaDatasource.postgresVersion` | PostgreSQL server version encoded as an integer (1300 = PostgreSQL 13, 1400 = PostgreSQL 14, 1500 = PostgreSQL 15, etc.). Must match the actual Postgres version backing the portal database so Grafana uses the correct query dialect. | `1300` | | `monitoring.grafanaDatasource.timescaledb` | Enable TimescaleDB support in the Grafana datasource. Set to `true` only if the portal database is running on TimescaleDB. | `false` | | `monitoring.alerts.platformController.goroutinesThreshold` | Goroutine count threshold for the platform controller | `1000` | | `monitoring.alerts.platformController.threadsThreshold` | Thread count threshold for the platform controller | `50` | | `monitoring.alerts.platformController.memoryBytesThreshold` | Allocated memory threshold (bytes) for the platform controller (~200 MiB) | `209715200` | | `monitoring.alerts.platformController.heapObjectsThreshold` | Heap object count threshold for the platform controller | `1536000` | | `monitoring.alerts.platformController.fileDescriptorsThreshold` | File descriptor count threshold for the platform controller | `300` | | `monitoring.alerts.portalServer.goroutinesThreshold` | Goroutine count threshold for the portal server | `500` | | `monitoring.alerts.portalServer.threadsThreshold` | Thread count threshold for the portal server | `50` | | `monitoring.alerts.portalServer.memoryBytesThreshold` | Allocated memory threshold (bytes) for the portal server (~350 MiB) | `367001600` | | `monitoring.alerts.portalServer.heapObjectsThreshold` | Heap object count threshold for the portal server | `1638400` | | `monitoring.alerts.portalServer.fileDescriptorsThreshold` | File descriptor count threshold for the portal server | `150` | | `monitoring.alerts.portalServer.transmittedBytesThreshold` | Transmitted bytes threshold (bytes per 10m) for the portal server (~1.5 GiB) | `1610612736` | | `monitoring.alerts.portalServer.slowResponseAvgSeconds` | Average response time threshold (integer seconds) for the slow response alert | `1` | | `monitoring.alerts.portalServer.slowResponseP90Seconds` | P90 response time threshold (integer seconds) for the slow response alert | `2` | | `monitoring.alerts.argoCD.enabled` | Enable Argo CD instance and heartbeat alerts (disable if not using Argo CD) | `true` | | `monitoring.alerts.argoCD.disconnectedWarningRatio` | Fraction of disconnected Argo CD clusters that triggers a warning (0-1) | `0.5` | | `monitoring.alerts.argoCD.disconnectedCriticalRatio` | Fraction of disconnected Argo CD clusters that triggers a critical alert (0-1) | `0.8` | | `monitoring.alerts.argoCD.unhealthyWarningRatio` | Fraction of connected but unhealthy Argo CD clusters that triggers a warning (0-1) | `0.5` | | `monitoring.alerts.argoCD.unhealthyCriticalRatio` | Fraction of connected but unhealthy Argo CD clusters that triggers a critical alert (0-1) | `0.8` | | `monitoring.alerts.kargo.enabled` | Enable Kargo instance and heartbeat alerts (disable if not using Kargo) | `true` | | `monitoring.alerts.kargo.disconnectedWarningRatio` | Fraction of disconnected Kargo agents that triggers a warning (0-1) | `0.6` | | `monitoring.alerts.kargo.disconnectedCriticalRatio` | Fraction of disconnected Kargo agents that triggers a critical alert (0-1) | `0.8` | | `monitoring.alerts.kargo.unhealthyWarningRatio` | Fraction of connected but unhealthy Kargo agents that triggers a warning (0-1) | `0.5` | | `monitoring.alerts.kargo.unhealthyCriticalRatio` | Fraction of connected but unhealthy Kargo agents that triggers a critical alert (0-1) | `0.8` | | `monitoring.alerts.reconciliation.slowReconcileP90Seconds` | Slow reconciliation loop p90 threshold (integer seconds; fractional values are rounded) | `2` | | `monitoring.alerts.reconciliation.slowEnqueueP90Seconds` | Slow enqueue loop p90 threshold (integer seconds; fractional values are rounded) | `1` | | `monitoring.alerts.addonController.slowReconcileP90Seconds` | Slow addon controller reconciliation loop p90 threshold (integer seconds; fractional values are rounded) | `5` | | `monitoring.alerts.addonController.slowEnqueueP90Seconds` | Slow addon controller enqueue loop p90 threshold (integer seconds; fractional values are rounded) | `1` | | `monitoring.alerts.notificationController.slowReconcileP90Seconds` | Slow notification controller reconciliation loop p90 threshold (integer seconds; fractional values are rounded) | `1` | | `monitoring.alerts.notificationController.slowEnqueueP90Seconds` | Slow notification controller enqueue loop p90 threshold (integer seconds; fractional values are rounded) | `1` | | `monitoring.alerts.notificationController.deliveryFailureRateThreshold` | Fraction of failed notification deliveries that triggers a warning (0-1, excludes web delivery method, requires >10 notifications) | `0.2` | | `monitoring.alerts.notificationController.pendingRateThreshold` | Fraction of pending notification deliveries that triggers a warning (0-1, excludes web delivery method, requires >10 notifications) | `0.8` | --- ## Database Operations The Akuity Platform uses [K3S](https://k3s.io/) as a lightweight Kubernetes control plane for each Argo CD and Kargo instance. K3S stores its data in PostgreSQL via [Kine](https://github.com/k3s-io/kine), which translates etcd API calls into SQL operations. **A healthy, well-provisioned database is the most important factor in K3S stability.** Every Kubernetes write operation (create, update, delete) inserts a row into the database. A background compaction process periodically removes old rows to keep the table from growing indefinitely. When the database cannot keep up, compaction falls behind, the table bloats, and the Argo CD or Kargo instance can become unstable. Self-hosted operators are responsible for database sizing, performance monitoring, and capacity planning. This page covers what to watch, how to interpret signs of trouble, and how to remediate issues. ## Database Health and Sizing A well-provisioned database prevents the majority of K3S stability issues. Monitor your database as you would any production workload: - **CPU**: Sustained saturation slows all query processing, including compaction. - **Memory**: Insufficient buffer pool causes excessive disk reads and slows queries. - **I/O**: Compaction is write-heavy. IOPS limits directly throttle how fast it can run. - **Connections**: An exhausted connection pool causes compaction transactions to queue or fail. - **Storage**: A database that runs out of storage will cause K3S to fail. Monitor headroom and set alerts well before limits are reached. For sizing guidance, see [PostgreSQL Database](./01-getting-started.mdx#postgresql-database) in the Getting Started guide. If you are consistently seeing K3S or compaction issues and suspect the database is undersized, scaling up CPU, memory, or IOPS is the right first step before investigating anything else. ## Monitoring The platform controller exposes two Prometheus metrics on the `/metrics` endpoint (port 9500) that can help diagnose compaction issues when K3S is behaving unexpectedly: | Metric | Labels | Description | |--------|--------|-------------| | `kine_lag_ratio` | `instance_id`, `instance_type` | Compaction lag as a multiple of the retention window | | `kine_actual_lag` | `instance_id`, `instance_type` | Raw revision count that compaction is behind | These metrics are **diagnostic tools**, not primary health indicators. An elevated `kine_lag_ratio` is a symptom, not a root cause. In most cases it reflects an underlying database constraint. Use these metrics to understand *why* something is wrong after your database metrics have already flagged a problem, not as the first signal to alert on. ### Understanding `kine_lag_ratio` The lag ratio expresses how far behind compaction is, normalized across instance sizes: ``` target_rev = current_rev - 1000 (min_retain) actual_lag = target_rev - compact_rev lag_ratio = actual_lag / 1000 ``` What constitutes a concerning value depends entirely on your environment. A stable ratio on a well-provisioned database with ample headroom may require no action at all. The same ratio trending upward on a database that is already constrained is a different situation. Always interpret it alongside your database metrics, not in isolation. ## Alerting **Alert on your database first.** Storage headroom, CPU utilization, I/O saturation, and connection pool exhaustion are the signals that indicate real risk. The Kine metrics can be useful as supporting context if you are already investigating K3S instability, but setting up aggressive alerts on `kine_lag_ratio` in isolation is likely to generate noise without actionable signal. A lag ratio that is elevated but stable on a healthy database generally does not require intervention. ## Troubleshooting K3S or Compaction Issues If K3S is behaving unexpectedly or you are seeing signs of compaction falling behind, work through the following in order. The database is almost always the root cause. ### 1. Check Database Health Start here before anything else. Check: - **CPU**: Is the database CPU saturated? - **Memory**: Is the database swapping or running low on buffer pool? - **I/O**: Are disk IOPS maxed out? - **Connections**: Is the connection pool exhausted? - **Storage**: How much headroom remains? If any of these are constrained, address them before proceeding. ### 2. Review Instance Load If the database is healthy but issues persist: - How many applications does the instance manage? - What is the sync frequency? Aggressive sync intervals generate more writes. - Are there runaway controllers or reconciliation loops? ### 3. Check K3S Compaction Logs Check K3S logs for `compact failed` messages. These indicate whether compaction transactions are timing out, hitting lock contention, or failing due to connection issues, and help distinguish between a database bottleneck and a compaction configuration issue. If you are seeing frequent failures and are unsure how to interpret them, [contact Akuity Support](https://support.akuity.io). ### 4. Tune Compaction Settings Only after confirming the database is healthy and instance load is reasonable, consider adjusting the `k3s` compaction parameters in the [Argo CD Instance Parameters](./31-helm-values-reference.md#argo-cd-instance-parameters) or [Kargo Instance Parameters](./31-helm-values-reference.md#kargo-instance-parameters) sections of the Helm Values Reference. If you are unsure which settings to adjust or want guidance based on your specific environment, [contact Akuity Support](https://support.akuity.io) before making changes. :::caution These settings compensate for environmental constraints. They do not fix underlying database performance problems. Adjusting them on a database that is already under heavy load can make things worse. ::: ### 5. Emergency Manual Compaction If compaction is critically behind and the instance is impaired, contact [Akuity Support](https://support.akuity.io) for assistance. This operation requires instance downtime and should only be performed after the underlying database issue has been identified and addressed. ## Further Reading - [Kine project](https://github.com/k3s-io/kine), the SQL backend for K3S - [Helm Values Reference](./31-helm-values-reference.md), full list of configurable parameters - [Argo CD Instance Parameters](./31-helm-values-reference.md#argo-cd-instance-parameters) - [Kargo Instance Parameters](./31-helm-values-reference.md#kargo-instance-parameters) --- ## Setup ## Prerequisites - [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator) or [kube-prometheus-stack](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack) installed in the cluster (provides the `ServiceMonitor` and `PrometheusRule` CRDs) - Grafana with the [sidecar](https://github.com/grafana-community/helm-charts/tree/main/charts/grafana#sidecar-for-dashboards) enabled for dashboards and datasources - The Grafana datasource sidecar must watch Secrets (or ConfigMaps) labeled with `grafana_datasource` The built-in Grafana resources are designed for the common Kubernetes pattern used by `kube-prometheus-stack` and the Grafana Helm chart: Grafana runs in the cluster and discovers dashboards and datasources via labeled ConfigMaps and Secrets. If you use external Grafana, Grafana Cloud, or Grafana Operator, keep the Prometheus resources enabled but plan to manage the dashboard and datasource through your existing Grafana workflow instead of relying on sidecar discovery. ## Enabling Monitoring Set `monitoring.enabled` to `true` in your Helm values: ```yaml monitoring: enabled: true ``` All sub-resources (ServiceMonitors, PrometheusRules, Grafana dashboard, Grafana datasource) are enabled by default once the top-level flag is set. You can selectively disable any of them: ```yaml monitoring: enabled: true serviceMonitors: enabled: true # ServiceMonitors for Prometheus scraping prometheusRules: enabled: true # Built-in alert rules grafanaDashboard: enabled: true # Grafana dashboard ConfigMap grafanaDatasource: enabled: true # Grafana PostgreSQL datasource Secret ``` If you only use Kargo or Argo CD, disable alerts for the one you are not using to avoid false-positive alerts: ```yaml monitoring: enabled: true alerts: kargo: enabled: false # disable if not using Kargo ``` If your Grafana deployment does not use sidecar discovery, disable the chart-managed Grafana resources and import or provision them separately: ```yaml monitoring: enabled: true grafanaDashboard: enabled: false grafanaDatasource: enabled: false ``` For the full list of `monitoring.*` parameters with defaults and descriptions, see the [Monitoring Parameters](../31-helm-values-reference.md#monitoring-parameters) section of the Helm values reference. That page is auto-generated from the chart's [`values.yaml`](https://github.com/akuityio/akuity-platform/tree/main/charts/akuity-platform), which also documents every option inline. ### Prometheus Selector Labels {#prometheus-selector-labels} Many Prometheus Operator installations use label selectors to filter which ServiceMonitors, PodMonitors, and PrometheusRules to discover. The chart defaults `additionalLabels` to `release: kube-prometheus-stack` on all three resource types, which matches the default selector used by [kube-prometheus-stack](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack). If your kube-prometheus-stack Helm release has a different name, override the label to match: ```yaml monitoring: enabled: true serviceMonitors: additionalLabels: release: my-prometheus # change to match your Helm release name podMonitors: additionalLabels: release: my-prometheus prometheusRules: additionalLabels: release: my-prometheus ``` :::tip If your ServiceMonitors or PodMonitors are being created but Prometheus is not scraping them, a label mismatch is almost always the cause. Check your Prometheus custom resource for `serviceMonitorSelector`, `podMonitorSelector`, and `ruleSelector` to see what labels are required. ::: ### Shared Monitoring Namespace If your Prometheus, Grafana, and Alertmanager run in a dedicated `monitoring` namespace, you can place all monitoring resources there instead of the Akuity Platform release namespace. This keeps everything co-located and avoids broadening Grafana sidecar permissions: ```yaml monitoring: enabled: true serviceMonitors: namespace: monitoring podMonitors: namespace: monitoring prometheusRules: namespace: monitoring grafanaDashboard: namespace: monitoring grafanaDatasource: namespace: monitoring ``` The `release: kube-prometheus-stack` label is included by default, so no `additionalLabels` override is needed unless your Helm release name differs (see [Prometheus Selector Labels](#prometheus-selector-labels)). :::tip This is a common approach for [kube-prometheus-stack](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack) installations because it keeps dashboards, rules, and scrape configuration alongside the monitoring stack. If your Grafana sidecar is scoped to specific namespaces instead of `ALL`, it also avoids extra cross-namespace configuration. ::: ### Grafana Datasource Provisioning By default, the chart provisions a Grafana PostgreSQL datasource Secret for the dashboard panels that query the portal database directly. The provisioned datasource: - Uses `database.readOnlyHost` when set, otherwise `database.host` - Uses `database.port`, `database.dbname`, `database.user`, `database.password`, and `database.sslmode` - Is created in `monitoring.grafanaDatasource.namespace`, defaulting to `monitoring.grafanaDashboard.namespace` and then the Helm release namespace If you already manage a Grafana datasource outside the chart, disable the built-in one: ```yaml monitoring: enabled: true grafanaDatasource: enabled: false ``` If you use a non-default schema or need custom datasource options beyond the chart defaults, manage the datasource separately in Grafana and keep `monitoring.grafanaDatasource.enabled: false`. This is also the recommended approach if you use external Grafana, Grafana Cloud, or Grafana Operator instead of a sidecar-based in-cluster Grafana deployment. ### Grafana Dashboard Folder To organize the dashboard into a specific Grafana folder, set `monitoring.grafanaDashboard.folder`. The chart writes a `grafana_folder` annotation on the dashboard ConfigMap, which the Grafana sidecar uses to place the dashboard in the named folder. :::note This requires your Grafana installation to have `sidecar.dashboards.folderAnnotation` set to `grafana_folder`. The upstream Grafana Helm chart does **not** set this by default. If you use [kube-prometheus-stack](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack) or the standalone [Grafana chart](https://github.com/grafana/helm-charts/tree/main/charts/grafana), add the following to your Grafana values: ```yaml sidecar: dashboards: folderAnnotation: grafana_folder ``` Without this, the annotation is ignored and the dashboard lands in the General folder. ::: ```yaml monitoring: enabled: true grafanaDashboard: folder: "Akuity Platform" ``` ## Verifying Your Setup {#verifying-your-setup} After enabling monitoring and deploying, verify each component is working. Monitoring resource names are prefixed with the Helm release name (e.g., `-platform-controller`). The examples below assume the default release name `akuity-platform`. ### 1. Check monitoring resources are created All chart-managed monitoring resources carry the label `app.kubernetes.io/part-of: akuity-platform`, so you can list them in one command: ```bash kubectl get servicemonitor,podmonitor,prometheusrule,configmap,secret \ -l app.kubernetes.io/part-of=akuity-platform -n ``` You should see ServiceMonitors for each enabled platform component (e.g. `-platform-controller`, `-portal-server`), PodMonitors for repo-server-delegate and repo-server-proxy, a PrometheusRule, a Grafana dashboard ConfigMap, and a Grafana datasource Secret. ### 2. Verify Prometheus is scraping targets Open the Prometheus UI (typically at `http://:9090`) and navigate to **Status > Targets**. Look for targets matching the Akuity Platform ServiceMonitors and PodMonitors. All targets should show a `UP` state. ServiceMonitor targets appear as `serviceMonitor//` and PodMonitor targets appear as `podMonitor//`. The PodMonitor targets (`-repo-server-proxy`, `-repo-server-delegate`) may show zero active targets if no Argo CD instances are using the Repo Server Delegate feature: this is expected. New targets may briefly appear as `UNKNOWN` immediately after the monitoring resources are created. This is expected until the first scrape completes. With the default `monitoring.serviceMonitors.interval: 60s`, allow up to one minute before treating this as a failure. If targets are missing, check that your ServiceMonitors and PodMonitors have the correct `additionalLabels` to match your Prometheus selectors (see [Prometheus Selector Labels](#prometheus-selector-labels) above). ### 3. Verify alerts are loaded ```bash kubectl get prometheusrule -n ``` You should see `akuity-platform-rules` (or `-rules` if you used a custom release name). To verify Prometheus has loaded the rules, navigate to **Status > Rules** in the Prometheus UI and search for `Akuity`. ### 4. Find the Grafana dashboard Open Grafana and search for "Akuity Platform" in the dashboard search. If the dashboard is not appearing, verify: - The Grafana sidecar is enabled and configured to watch ConfigMaps with the `grafana_dashboard` label - The dashboard ConfigMap is in a namespace the sidecar watches (see [Shared Monitoring Namespace](#shared-monitoring-namespace) for the recommended setup) If you intentionally disabled `monitoring.grafanaDashboard.enabled`, import the bundled dashboard JSON into Grafana using your normal workflow instead. ### 5. Verify the Grafana datasource exists Open Grafana and navigate to **Connections > Data sources**. You should see a PostgreSQL datasource named ` Portal DB` unless you overrode `monitoring.grafanaDatasource.datasourceName`. If it is missing, verify: - The Grafana datasource sidecar is enabled - The sidecar watches Secrets labeled with `grafana_datasource` - The datasource Secret is in a namespace the sidecar watches If you intentionally disabled `monitoring.grafanaDatasource.enabled`, provision an equivalent PostgreSQL datasource in Grafana yourself and ensure its UID matches the one referenced by the dashboard, or update the dashboard to point at your datasource. ## Scraped Components ### ServiceMonitors ServiceMonitors are created for each platform component that exposes a metrics endpoint. Components gated by an `enabled` flag only get a ServiceMonitor when that component is also enabled. | Component | Metrics Port | Condition | |-----------|-------------|-----------| | platform-controller | 9500 | Always | | portal-server | 9501 | Always | | notification-controller | 9505 | Only when `notificationController.enabled: true` | | addon-controller | 9506 | Only when `addonController.enabled: true` | ### PodMonitors PodMonitors scrape metrics from pods in Argo CD instance namespaces (`argocd-*`). Unlike ServiceMonitors, they use `namespaceSelector.any: true` to discover pods across all namespaces. | PodMonitor | Selector | Port | Notes | |------------|----------|------|-------| | repo-server-delegate | `akuity.io/repo-server-delegate` label exists | `metrics` | Only produces targets when instances use the [Repo Server Delegate](../../03-argocd/02-managing-instances/30-settings/10-features/10-manifest-generation.md#repo-server-delegate) feature | | repo-server-proxy | `akuity.io/repo-server-proxy: "true"` | `akuity-metrics` | Drops the high-cardinality `repo_server_proxy_method_duration_seconds_bucket` metric via metricRelabeling to control storage costs | Both PodMonitors are enabled by default when `monitoring.podMonitors.enabled` is `true`. It is safe to leave them enabled even when no instances use the Repo Server Delegate feature: the PodMonitors simply match zero pods. ## Grafana Dashboard The bundled Grafana dashboard provides visibility into: - **Argo CD Instances**: health distribution, reconciliation status, instance counts, tables of unhealthy/unreconciled instances - **Argo CD Clusters**: connection status, reconciliation, health breakdown - **Kargo Instances**: health, reconciliation, instance counts - **Kargo Agents**: connection status, reconciliation, health breakdown - **Control Plane Operations**: controller workqueue depth and duration, OOM-killed containers, database connection pool stats, persistent volume usage, CPU throttling - **Argo CD Repo Server Delegate (Optional)**: reverse-proxy latency, request rate, and pending requests for instances using the Repo Server Delegate feature The dashboard includes configurable template variables: - **DS_PROMETHEUS**: Prometheus datasource for metrics panels (health gauges, time series, alert-derived stats) - **DS_PORTAL_DB**: PostgreSQL datasource for table panels that query the portal database directly (instance lists, cluster details, org breakdowns). The chart provisions this datasource by default through `monitoring.grafanaDatasource.*`. If you disable that datasource or manage your own, those panels will fail until `DS_PORTAL_DB` resolves to a working PostgreSQL datasource. - **namespace**: filters metrics to the selected Kubernetes namespace - **ThrottlingRatio**: threshold used by the CPU-throttled containers panel The **Argo CD Repo Server Delegate (Optional)** row may be empty. It only shows data when both of the following are true: - the Argo CD instance is configured to use [`repoServerDelegate`](../../03-argocd/02-managing-instances/30-settings/10-features/10-manifest-generation.md#repo-server-delegate) in either `controlPlane` or `managedCluster` mode - instance-level Prometheus metrics are enabled on the platform controller (for self-hosted installs this is typically done by setting `platformController.env.ENABLE_INSTANCE_PROMETHEUS_MONITORING: "true"`) The bundled chart includes PodMonitors (`monitoring.podMonitors.enabled`) that scrape repo-server-delegate and repo-server-proxy metrics across instance namespaces (`argocd-*`). If an instance uses the default "all managed clusters" manifest generation layout, this row will remain empty because there is no delegated repo server reverse-proxy traffic to display. --- ## Alert Reference The bundled PrometheusRule includes alerts organized by component. Alerts that reference configurable thresholds can be tuned through `monitoring.alerts.*` Helm values (see [Monitoring Parameters](../31-helm-values-reference.md#monitoring-parameters) in the Helm values reference). Every alert includes a `runbook_url` annotation that links directly to the relevant section below. When an alert fires, the runbook link is available in Alertmanager, PagerDuty, Slack, and other notification integrations. ## Platform Controller - Hardware {#platform-controller-hardware} These alerts fire when the platform controller process exceeds resource thresholds, which may indicate a memory leak, excessive concurrency, or resource exhaustion. Each fires at warning severity when the named resource exceeds its `monitoring.alerts.platformController.*Threshold` for 1h: - `AkuityPlatformControllerTooManyGoroutines` - `AkuityPlatformControllerTooManyThreads` - `AkuityPlatformControllerHighMemory` - `AkuityPlatformControllerTooManyHeapObjects` - `AkuityPlatformControllerTooManyFileDescriptors` :::tip The file descriptor alerts use the `container_file_descriptors` metric from cAdvisor/kubelet. This metric may not be available on all Kubernetes providers. If the metric is absent, these alerts will simply remain inactive: they will not cause errors. ::: **Remediation:** - Check platform controller logs for goroutine leaks or unexpected activity - Review recent configuration changes that may have increased load - Consider increasing resource limits on the platform controller deployment - Restart the platform controller pod if values remain elevated after the underlying cause is resolved ## Platform Controller - Argo CD Instances {#platform-controller-argo-cd-instances} These alerts monitor the health and reconciliation status of managed Argo CD instances. Critical unless noted: - `AkuityUnhealthyArgoInstances` - `AkuityUnreconciledArgoInstances` - `AkuityDegradedArgoInstances` - `AkuityArgoInstanceEventsSyncFailed` - `AkuityUnreconciledArgoClusters` - `AkuityDegradedArgoClusters` - `AkuityHighDisconnectedArgoClusters` (warning) / `AkuityHighDisconnectedArgoClustersCritical` - `AkuityHighUnhealthyArgoClusters` (warning) / `AkuityHighUnhealthyArgoClustersCritical` The disconnected and unhealthy ratio thresholds are configurable via `monitoring.alerts.argoCD.disconnectedWarningRatio`, `monitoring.alerts.argoCD.disconnectedCriticalRatio`, `monitoring.alerts.argoCD.unhealthyWarningRatio`, and `monitoring.alerts.argoCD.unhealthyCriticalRatio`. Small fleets where a single disconnected cluster represents a large percentage may want to raise the warning threshold. **Remediation:** - Check the platform controller logs for reconciliation errors - Verify the database is healthy and accessible (see [Database Operations](../35-database-operations.md)) - For disconnected clusters, verify network connectivity between the agent and the platform - For degraded instances, check the Argo CD instance namespace for pod status and events - Review recent changes to instance configuration ## Platform Controller - Kargo Instances {#platform-controller-kargo-instances} These alerts monitor Kargo instances and agents using the same pattern as the Argo CD alerts above, with two intentional differences: - **Unhealthy timeout is 30m** (vs 40m for Argo CD). Kargo's reconciliation loop is faster, so a 30-minute window gives the same margin with less lag. - **Disconnected agent warning threshold is 60%** (vs 50% for Argo CD clusters). Kargo agents have a higher expected transient-disconnection rate during warehouse syncs, so the warning fires at a higher ratio to reduce noise. Critical unless noted: - `AkuityUnhealthyKargoInstances` - `AkuityUnreconciledKargoInstances` - `AkuityDegradedKargoInstances` - `AkuityKargoInstanceEventsSyncFailed` - `AkuityUnreconciledKargoAgents` - `AkuityDegradedKargoAgents` - `AkuityHighDisconnectedKargoAgents` (warning) / `AkuityHighDisconnectedKargoAgentsCritical` - `AkuityHighUnhealthyKargoAgents` (warning) / `AkuityHighUnhealthyKargoAgentsCritical` The ratio thresholds are configurable via `monitoring.alerts.kargo.disconnectedWarningRatio`, `monitoring.alerts.kargo.disconnectedCriticalRatio`, `monitoring.alerts.kargo.unhealthyWarningRatio`, and `monitoring.alerts.kargo.unhealthyCriticalRatio`. **Remediation:** Same approach as Argo CD instance alerts above. Check platform controller logs, database health, and network connectivity. ## Platform Controller - Reconciler {#platform-controller-reconciler} These alerts detect operational issues with the platform controller's internal reconciliation loops. - `AkuityMetricsCollectorRefreshErrors` (critical) - `AkuitySlowMetricsCollectorRefresh` (warning) - `AkuityPlatformControllerReconcilerErrors` (warning) - `AkuityMissingDBMetricsCollectorHeartbeat` (critical) - `AkuitySlowReconciliationLoop` (warning): configurable at `monitoring.alerts.reconciliation.slowReconcileP90Seconds` - `AkuitySlowEnqueueLoop` (warning): configurable at `monitoring.alerts.reconciliation.slowEnqueueP90Seconds` - `AkuityMissing*Heartbeat`: 12 critical heartbeat alerts, one per reconciliation loop **Remediation:** - **Missing heartbeat** alerts typically indicate the platform controller is not running or has crashed. Check pod status and logs. - **Slow reconciliation** may indicate database performance issues or high load. Check database metrics and connection pool health (see [Database Operations](../35-database-operations.md)). - **Metrics collector errors** suggest the platform controller cannot query the database for status metrics. Verify database connectivity. ## Portal Server - Hardware {#portal-server-hardware} Each fires at warning severity when the named resource exceeds its `monitoring.alerts.portalServer.*Threshold`: - `AkuityPortalServerTooManyGoroutines` - `AkuityPortalServerTooManyThreads` - `AkuityPortalServerHighMemory` - `AkuityPortalServerTooManyHeapObjects` - `AkuityPortalServerTooManyFileDescriptors` - `AkuityPortalServerTooManyTransmittedBytes` **Remediation:** Same approach as platform controller hardware alerts. The portal server handles API traffic, so elevated values may correlate with high request volume. The transmitted bytes alert detects runaway network egress, which may indicate a streaming loop or unexpectedly large API responses. ## Portal Server - Application {#portal-server-application} - `AkuityPortalServerErrors` (critical): any HTTP 5xx from the portal API. - `AkuityPortalServerSlowResponses` (warning): average response time above `monitoring.alerts.portalServer.slowResponseAvgSeconds`. - `AkuityPortalServerSlowResponsesP90` (warning): p90 response time above `monitoring.alerts.portalServer.slowResponseP90Seconds`. The response time thresholds are configurable via `monitoring.alerts.portalServer.slowResponseAvgSeconds` and `monitoring.alerts.portalServer.slowResponseP90Seconds`. Self-hosted installations on slower hardware or with higher-latency database connections may want to raise these thresholds. **Remediation:** - Check portal server logs for error details - Review database query performance - Check for upstream service degradation (SSO provider, etc.) - Review recent deployments for regressions ## Addon Controller {#addon-controller} Only deployed when `addonController.enabled: true`. - `AkuityAddonControllerErrors` (warning) - `AkuitySlowAddonControllerReconciliation` (warning): configurable at `monitoring.alerts.addonController.slowReconcileP90Seconds` - `AkuitySlowAddonControllerEnqueue` (warning): configurable at `monitoring.alerts.addonController.slowEnqueueP90Seconds` - `AkuityMissingAddonController*Heartbeat`: 3 critical heartbeat alerts **Remediation:** - Check addon controller logs for error details - Verify the addon controller pod is running and not crash-looping - Review recent changes to addon definitions or cluster addon configurations - For heartbeat alerts, restart the addon controller pod if it appears stuck ## Notification Controller {#notification-controller} Only deployed when `notificationController.enabled: true`. - `AkuityNotificationControllerErrors` (warning) - `AkuitySlowNotificationControllerReconciliation` (warning): configurable at `monitoring.alerts.notificationController.slowReconcileP90Seconds` - `AkuitySlowNotificationControllerEnqueue` (warning): configurable at `monitoring.alerts.notificationController.slowEnqueueP90Seconds` - `AkuityMissingNotificationController*Heartbeat`: 3 critical heartbeat alerts - `AkuityHighNotificationDeliveryFailureRate` (warning): configurable at `monitoring.alerts.notificationController.deliveryFailureRateThreshold` - `AkuityHighNotificationPendingRate` (warning): configurable at `monitoring.alerts.notificationController.pendingRateThreshold` The delivery failure and pending rate thresholds are configurable via `monitoring.alerts.notificationController.deliveryFailureRateThreshold` and `monitoring.alerts.notificationController.pendingRateThreshold`. Both alerts exclude the `web` delivery method and require at least 10 notifications in the window to avoid noisy alerts on low-volume deployments. **Remediation:** - Check notification controller logs for error details - Verify SMTP configuration if using email delivery - Review notification target availability (webhooks, Slack, etc.) --- ## Operations ## Alertmanager Routing {#alertmanager-routing} All bundled alerts use names prefixed with `Akuity`, making it straightforward to route them in Alertmanager. Below are example configurations for common notification targets. ### Slack ```yaml # alertmanager.yaml route: routes: - matchers: - alertname=~"Akuity.*" receiver: akuity-slack group_by: ['alertname'] group_wait: 30s group_interval: 5m repeat_interval: 4h receivers: - name: akuity-slack slack_configs: - channel: '#akuity-platform-alerts' send_resolved: true title: '{{ .GroupLabels.alertname }}' text: >- {{ range .Alerts }} *{{ .Annotations.summary }}* {{ .Annotations.description }} Runbook: {{ .Annotations.runbook_url }} {{ end }} ``` ### PagerDuty ```yaml route: routes: - matchers: - alertname=~"Akuity.*" - severity=~"critical|warning" receiver: akuity-pagerduty receivers: - name: akuity-pagerduty pagerduty_configs: - routing_key: '' description: '{{ .GroupLabels.alertname }}: {{ (index .Alerts 0).Annotations.summary }}' links: - href: '{{ (index .Alerts 0).Annotations.runbook_url }}' text: 'Runbook' ``` ### Severity-based routing To page on critical alerts and send warnings to a lower-priority channel: ```yaml route: routes: - matchers: - alertname=~"Akuity.*" - severity="critical" receiver: akuity-pagerduty - matchers: - alertname=~"Akuity.*" - severity="warning" receiver: akuity-slack ``` ## Tuning Alert Thresholds {#tuning-alert-thresholds} The bundled alert thresholds are designed for typical production deployments. Depending on your scale and workload patterns, you may want to adjust them. ### When to tune - **Small deployments** (fewer than 10 Argo CD instances): Hardware thresholds like goroutine count and memory usage may be set higher than your platform controller will ever reach under normal conditions. This is fine: alerts simply won't fire. No action is needed unless you want tighter bounds for your environment. - **Small fleets** (fewer than ~10 clusters or agents): The ratio-based disconnected/unhealthy alerts (`monitoring.alerts.argoCD.*`, `monitoring.alerts.kargo.*`) can be noisy when a single disconnected cluster represents a large fraction of the fleet. Consider raising the warning ratio. - **Large deployments** (hundreds of instances or clusters): Reconciliation loop thresholds (`slowReconcileP90Seconds`, `slowEnqueueP90Seconds`) may need to be relaxed, as larger instance counts naturally increase reconciliation time. - **Resource-constrained environments**: If you run the platform controller or portal server with tight memory limits, consider lowering the memory threshold to alert before OOM kills occur. - **Higher-latency infrastructure**: If the portal server connects to a remote database or runs on slower hardware, consider raising `monitoring.alerts.portalServer.slowResponseAvgSeconds` and `slowResponseP90Seconds`. ### How to tune Override any threshold through the `monitoring.alerts.*` values. See the [Monitoring Parameters](../31-helm-values-reference.md#monitoring-parameters) section of the Helm values reference for the full list, defaults, and descriptions. :::tip After adjusting thresholds, verify the updated values in the Prometheus UI under **Status > Rules**. Search for the alert name to confirm the new threshold is active. ::: ## Disabling Monitoring {#disabling-monitoring} Monitoring resources can be safely removed by setting `monitoring.enabled` back to `false` and re-applying the chart: ```yaml monitoring: enabled: false ``` This cleanly removes all monitoring resources (ServiceMonitors, PrometheusRule, Grafana dashboard ConfigMap, and Grafana datasource Secret) regardless of which namespace they were deployed to. The platform components themselves are unaffected: disabling monitoring does not restart or modify any running pods. Prometheus will stop scraping the targets once the ServiceMonitors are deleted, and Grafana's sidecar will remove the dashboard and datasource on its next reconciliation cycle. You can also selectively disable individual monitoring sub-resources without turning off monitoring entirely. For example, to keep Prometheus scraping and alerts but remove the Grafana integration: ```yaml monitoring: enabled: true grafanaDashboard: enabled: false grafanaDatasource: enabled: false ``` ## Grafana Datasource and External Secrets {#grafana-datasource-external-secrets} The auto-provisioned Grafana datasource reads database credentials from the same `database.*` Helm values that the platform components use (`database.host`, `database.user`, `database.password`, etc.). For most deployments this works out of the box with no additional configuration because the platform already requires these values to connect to PostgreSQL. ### External secrets management If you manage database credentials through an external secrets solution (e.g., [External Secrets Operator](https://external-secrets.io/), [OpenBao](https://openbao.org/), or cloud-native IAM authentication), the `database.password` value may not be set in your Helm values. In this case, disable the auto-provisioned datasource and manage it through your existing secrets workflow: ```yaml monitoring: enabled: true grafanaDatasource: enabled: false ``` Then provision an equivalent PostgreSQL datasource in Grafana with matching credentials. To ensure the bundled dashboard panels work, either: - Set the datasource UID to match `-portal-db` (e.g., `akuity-platform-portal-db`), or - Update the `DS_PORTAL_DB` template variable in the dashboard to point at your datasource after import ### Non-default database schema If your installation uses a custom `database.schemaname` (anything other than `public`), the auto-provisioned Grafana datasource will connect successfully but dashboard SQL panels that reference unqualified table names (e.g. `organization`, `argo_cd_instance`) may fail because the Grafana PostgreSQL plugin does not support setting `search_path` through its provisioning configuration. To work around this, set `search_path` on the PostgreSQL role that Grafana uses to connect: ```sql ALTER ROLE SET search_path TO '', 'public'; ``` This takes effect on every new connection from that role and requires no Grafana configuration changes. Alternatively, disable the auto-provisioned datasource and manage your own with schema-qualified table names or a role-level `search_path`: ```yaml monitoring: enabled: true grafanaDatasource: enabled: false ``` ### IAM-based database authentication For databases using IAM authentication (e.g., AWS RDS IAM, GCP Cloud SQL IAM), the platform components typically receive credentials through pod-level service account bindings rather than a static password in Helm values. The auto-provisioned Grafana datasource does not support this pattern. Disable it and configure a Grafana datasource that uses your IAM-compatible authentication method instead. ## Custom Alerts You can add your own alert or recording rules alongside the bundled ones using `monitoring.prometheusRules.additionalRules`: ```yaml monitoring: enabled: true prometheusRules: additionalRules: - alert: AkuityPodRestartLoop expr: | increase(kube_pod_container_status_restarts_total{namespace="akuity"}[1h]) > 5 for: 10m labels: severity: warning annotations: summary: "Pod {{ $labels.pod }} is restarting frequently" description: >- Pod {{ $labels.pod }} in namespace {{ $labels.namespace }} has restarted {{ $value }} times in the last hour. ``` ## Further Reading - [`values.yaml`](https://github.com/akuityio/akuity-platform/tree/main/charts/akuity-platform): full list of configurable `monitoring.*` parameters (see the `monitoring` section) - [Database Operations](../35-database-operations.md): database-specific monitoring and Kine metrics --- ## Monitoring(36-monitoring) The Akuity Platform Helm chart includes optional monitoring resources that integrate with the [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator) and Grafana. When enabled, the chart deploys: - **ServiceMonitors** for Prometheus scraping of platform components - **PrometheusRule** with curated alert definitions for platform health - **Grafana dashboard** as a ConfigMap, auto-discovered by sidecar-based Grafana installs - **Grafana PostgreSQL datasource** as a Secret, auto-discovered by the Grafana datasource sidecar so dashboard panels that query the portal database work out of the box --- ## Self-Hosted Akuity Platform Support # Self-Hosted AKP Support --- ## Release Cycle - Akuity will release a new version of the Akuity Platform (AKP) at least once per quarter. ## Supported Versions - Akuity will support the current Major release and the three most recent Minor releases within that release. - If the current major release has fewer than 3 minor versions, Akuity will include support for the last Minor version of the last Major release. - For example, if the current version is 1.1 and the last version of the last major release was 0.9, then Akuity will support 1.1, 1.0 and 0.9. ## Current Version - The current version of Self-Hosted AKP can be found [here](https://docs.akuity.io/changelog/selfhosted/) --- ## Self Hosted Akuity Platform --- ## Introduction to Argo CD This tutorial will walk you through implementing Argo CD with the Akuity Platform, to manage the deployment of the Helm charts in a declarative fashion. Ultimately, you will have a Kubernetes cluster, with Applications deployed using an Argo CD control plane. A video version of this tutorial is available with an introduction to Continous Delivery, GitOps, and Argo CD. 👇 - [1. Prerequisites](#1-prerequisites) - [2. Setting up Your Environment](#2-setting-up-your-environment) - [2.1. Create the Repository from a Template](#21-create-the-repository-from-a-template) - [2.1.1. Verify Environment](#211-verify-environment) - [2.2. Akuity Platform Sign Up](#22-akuity-platform-sign-up) - [2.3. Create your Argo CD Instance](#23-create-your-argo-cd-instance) - [2.3.1. Configure Your Instance](#231-configure-your-instance) - [2.4. Deploy an Agent to the Cluster](#24-deploy-an-agent-to-the-cluster) - [3. Using Argo CD to Deploy Helm Charts](#3-using-argo-cd-to-deploy-helm-charts) - [3.1. Create an Application in Argo CD](#31-create-an-application-in-argo-cd) - [3.2. Syncing Changes Manually](#32-syncing-changes-manually) - [3.3. Enable Auto-sync and Self-heal for the Guestbook Application](#33-enable-auto-sync-and-self-heal-for-the-guestbook-application) - [3.4. Demonstrate Application Auto-sync via Git](#34-demonstrate-application-auto-sync-via-git) - [4. Managing Argo CD Applications Declaratively](#4-managing-argo-cd-applications-declaratively) - [4.1. Create an App of Apps](#41-create-an-app-of-apps) - [5. Tool Detection, and Sync Waves](#5-tool-detection-and-sync-waves) - [5.1. Tool Detection](#51-tool-detection) - [5.2. Sync Phases, Waves, \& Hooks](#52-sync-phases-waves--hooks) - [5.3. Sync It!](#53-sync-it) - [6. Review](#6-review) ## 1. Prerequisites To follow this tutorial make sure you have minimal working knowledge of the following concepts: - [Kubernetes](https://youtu.be/4ht22ReBjno?t=164) - [GitOps](https://akuity.io/gitops) - [Argo CD](https://argo-cd.readthedocs.io) The tutorial requires that you also have a [GitHub](https://github.com/) Account. You will use this to: - host a **public** repo for the GitOps configuration. - utilize [GitHub Codespaces](https://github.com/features/codespaces) for the workshop environment. Ensure that you have a quota available. The free tier includes 4 vCPU at 30 hours a month. - create an account on the Akuity Platform. The tutorial was written and tested using the following tool and component versions: - Argo CD: v2.10.1 - Docker Desktop: 4.13.1 - Kubernetes: v1.27.13-k3s1 - k3d: v5.4.1 ## 2. Setting up Your Environment ### 2.1. Create the Repository from a Template In this scenario, you manage the application Helm charts in version control. To represent this in the lab, you will create a repository from a template containing the application Helm charts. 1. Click [this link](https://github.com/akuity/intro-argo-cd-tutorial-template/generate) or click "Use this template" from the [`akuity/intro-argo-cd-tutorial-template`](https://github.com/akuity/intro-argo-cd-tutorial-template) repo main page. 2. Ensure the desired "Owner" is selected (e.g., your account and not an organization). 3. Enter `intro-argo-cd` for the "Repository name". 4. Then click Create repository from template. 5. Next, you'll start a new Codespace by clicking the green Code button on the repo page, selecting the Codespaces tab, and then selecting Create codespace on main. :::warning If you have other codespaces running, you may run into usage limits. You should shutdown codespaces that you are not using. ::: The Codespace will open in another browser tab with information about setting up your codespace. Once it's done setting up, you should see a terminal in the browser with the repo open. #### 2.1.1. Verify Environment Part of the codespace setup was to install all necessary tools, which includes setting up `k3d` and `kubectl`. You can verify that the environment is ready by going through the following: 1. Verify that `k3d` is installed and running a Kubernetes cluster. ``` k3d cluster list ``` You should see the following output: ``` NAME SERVERS AGENTS LOADBALANCER dev 1/1 0/0 true ``` 2. Check that the cluster works by running `kubectl get nodes`. ``` % kubectl get nodes NAME STATUS ROLES AGE VERSION dev-control-plane Ready control-plane 7m44s v1.29.2 ``` Fetching the nodes will demonstrate that `kubectl` can connect to the cluster and query the API server. The node should be in the "Ready" status. ### 2.2. Akuity Platform Sign Up This scenario demonstrates deploying applications to a cluster external to Argo CD. Similar to how the GitHub repo is hosting the Helm charts, which describe **what** resources to deploy into Kubernetes, the Akuity Platform will host the Application manifests, which represent **how** to deploy the resources into the cluster. Along with Argo CD, which will implement the changes on the cluster. :::tip [Sign up](https://training.akuity.cloud/) for a free 30-day trial of the Akuity Platform! ::: 1. Create an account on the [Akuity Platform](https://training.akuity.cloud/). 2. To log in with GitHub SSO, click "Continue with GitHub". :::note You can also use Google SSO or an email and password combo. ::: 3. Click Authorize akuityio. 4. Click the create or join link. 5. Click + New organization in the upper right hand corner of the dashboard. 6. Name your organization following the rules listed below the Organization Name field. ### 2.3. Create your Argo CD Instance You can create your Argo CD instance using the Akuity Platform **Dashboard or CLI** by choosing between the tabs below. **Dashboard** 7. Navigate to Argo CD. 8. Click + Create in the upper right hand corner of the dashboard. 9. Name your instance following the rules listed below the Instance Name field. 10. (Optionally) Choose the Argo CD version you want to use. 11. Click + Create. At this point, your Argo CD instance will begin initializing. The start-up typically takes under 2 minutes. #### 2.3.1. Configure Your Instance While the instance is initializing, you can prepare it for the rest of the lab. 1. In the dashboard for the Argo CD instance, click Settings. 2. On the inner sidebar, under "Security & Access", click System Accounts. 3. Enable the "Admin Account" by clicking the toggle and clicking Confirm on the prompt. 4. Then, for the `admin` user, click Set Password. 5. Click Regenerate Password, then click Copy. 6. In the bottom right of the Set password prompt, hit Close. 7. In the top, next to the Argo CD instance name and status, click the instance URL (e.g., `.cd.akuity.cloud`) to open the Argo CD login page in a new tab. 8. Enter the username `admin` and the password copied previously. You now have a fully-managed Argo CD instance 🎉 ### 2.4. Deploy an Agent to the Cluster You must connect the cluster to Argo CD to deploy the application resources. The Akuity Platform uses an agent-based architecture for connecting external clusters. So, you will provision an agent and deploy it to the cluster. 1. Back on the Akuity Platform, in the top left of the dashboard for the Argo CD instance, click Clusters. 2. In the top right, click Connect a cluster. 3. Enter the `dev` name as the "Cluster Name". 4. In the bottom right, click Connect Cluster. 5. To get the agent install command, click Copy to Clipboard. Then, in the bottom right, Done. 6. Open your terminal and check that your target is the correct cluster by running `kubectl config current-context`. If you are following along using `k3d`, you should see the following: ``` % kubectl config current-context k3d-dev ``` 7. Paste and run the command against the cluster. The command will create the `akuity` namespace and deploy the resources for the Akuity Agent. 8. Check the pods in the `akuity` namespace. Wait for the `Running` status on all pods (approx. 1 minute). ``` % kubectl get pods -n akuity NAME READY STATUS RESTARTS AGE akuity-agent-- 1/1 Running 0 65s akuity-agent-- 1/1 Running 0 65s argocd-application-controller-- 2/2 Running 0 65s argocd-notifications-controller-- 1/1 Running 0 65s argocd-redis-- 1/1 Running 0 65s argocd-repo-server-- 1/1 Running 0 64s argocd-repo-server-- 1/1 Running 0 64s ``` Re-run the `kubectl get pods -n akuity` command to check for updates on the pod statuses. 9. Back on the Clusters dashboard, confirm that the cluster shows a green heart before the name, indicating a healthy status. **CLI** 1. Check your `akuity` CLI version. ``` akuity version ``` 2. Log into the `akuity` CLI. ``` akuity login ``` - Open the link displayed, enter the code. 3. Set your organization name in the `akuity` config ``` akuity config set --organization-name= ``` :::info You can find your organization name by running `akuity org list`. ``` ID NAME ROLES r89390kxc0sf8y5r akuity-bot owner ``` Replace `` with your organization's name. Or do it in one command with some bash-fu: ``` akuity config set --organization-id=$(akuity org list | awk 'NR==2 {print $1}') ``` ::: 4. Create the Argo CD instance on the Akuity Platform ``` akuity argocd apply -f akuity-platform/ ``` 5. Apply the agent install manifests to the cluster. ``` akuity argocd cluster get-agent-manifests --instance-name=argo-cd dev | kubectl apply -f - ``` 6. From the Akuity Platform Dashboard, in the top, next to the Argo CD instance name and status, click the instance URL (e.g., `.cd.akuity.cloud`) to open the Argo CD login page in a new tab. 7. Enter the username `admin` and the password `akuity-argocd`. You now have a fully-managed Argo CD instance 🎉 ## 3. Using Argo CD to Deploy Helm Charts ### 3.1. Create an Application in Argo CD Now, using an Application, you will declaratively tell Argo CD how to deploy the Helm charts. Start by creating an Application to deploy the `guestbook` Helm Chart from the repo. **Dashboard** 1. Navigate to the Argo CD UI, and click NEW APP. 2. In the top right, click EDIT AS YAML. 3. Paste the contents of `apps/guestbook-dev.yaml` from your repo. :::info This manifest describes an Application. - The name of the Application is `guestbook-dev`. - The source is your repo with the Helm charts. - The destination is the cluster connected by the agent. - The sync policy will automatically create the namespace. ::: 4. Click SAVE. At this point, the UI has translated the Application manifest into the corresponding fields in the wizard. 5. In the top left, click CREATE. The new app pane will close and show the card for the Application you created. The status on the card will show "Missing" and "OutOfSync". 6. Click on the Application card titled `argocd/guestbook-dev`. :::info In this state, the Application resource tree shows the manifests generated from the source repo URL and path defined. You can click DIFF to see what manifests the Application rendered. Since auto-sync is disabled, the resources do not exist in the destination yet. ::: 7. In the top bar, click SYNC then SYNCHRONIZE to instruct Argo CD to create the resources defined by the Application. The resource tree will expand as the Deployment creates a ReplicaSet that makes a pod, and the Service creates an Endpoint and EndpointSlice. The Application will remain in the "Progressing" state until the pod for the deployment is running. Afterwards, all the top-level resources (i.e., those rendered from the Application source) in the tree will show a green checkmark, indicating that they are synced (i.e., present in the cluster). ### 3.2. Syncing Changes Manually An Application now manages the deployment of the `guestbook` Helm chart. So what happens when you want to deploy a new image tag? Instead of running `helm upgrade guestbook-dev ./guestbook`, you will trigger a sync of the Application. 1. Navigate to your repo on GitHub, and open the file `guestbook/values-dev.yaml`. 2. In the top right of the file, click the pencil icon to edit. 3. Override the default `image.tag` value by setting it to `0.2.0`. ```yaml image: tag: 0.2.0 ``` 4. Click Commit changes.... 5. Add a commit message. For example `chore(guestbook): bump dev tag to 0.2.0`. 6. Click Commit changes. 7. Switch to the Argo CD UI and go to the `argocd/guestbook-dev` Application. 8. In the top right, click the REFRESH button to trigger Argo CD to check for any changes to the Application source and resources. :::note The default sync interval is 3 minutes. Any changes made in Git may not apply for up to 3 minutes. ::: 9. In the top bar, click SYNC then SYNCHRONIZE to instruct Argo CD to deploy the changes. Due to the change in the repo, Argo CD will detect that the Application is out-of-sync. It will template the Helm chart (i.e., `helm template`) and patch the `guestbook-dev` deployment with the new image tag, triggering a rolling update. ### 3.3. Enable Auto-sync and Self-heal for the Guestbook Application Now that you are using an Application to describe how to deploy the Helm chart into the cluster, you can configure the sync policy to automatically apply changes — removing the need for developers to manually trigger a deployment for changes that already made it through the approval processes. 1. In the top menu, click DETAILS. 2. Under the SYNC POLICY section, click ENABLE AUTO-SYNC and on the prompt, click OK. 3. Below that, on the right of "SELF HEAL", click ENABLE. 4. In the top right of the DETAILS pane, click the X to close it. If the Application was out-of-sync, this would immediately trigger a sync. In this case, your Application is already in sync, so Argo CD made no changes. ### 3.4. Demonstrate Application Auto-sync via Git With auto-sync enabled on the `guestbook-dev` Application, changes made to the `main` branch in the repo will be applied automatically to the cluster. You will demonstrate this by updating the number of replicas for the `guestbook-dev` deployment. 1. Navigate to your repo on Github, and open the file `guestbook/values.yaml`. 2. In the top right of the file, click the pencil icon to edit. 3. Update the `replicaCount` to the `2` list. 4. In the top right, click Commit changes.... 5. Add a commit message. For example `chore(guestbook): scale to 2 replicas`. 6. In the bottom left, click Commit changes. 7. Switch to the Argo CD UI and go to the `argocd/guestbook-dev` Application. 8. In the top right, click the REFRESH button to trigger Argo CD to check for any changes to the Application source and resources. You can view the details of the sync operation by, in the top menu, clicking SYNC STATUS. Here it will display, what "REVISION" it was for, what triggered it (i.e., "INITIATED BY: automated sync policy"), and the result of the sync (i.e., what resources changed). ## 4. Managing Argo CD Applications Declaratively ### 4.1. Create an App of Apps One of the benefits of using Argo CD is that you are now codifying the deployment process for the Helm charts in the Application spec. Earlier in the lab, you created the `guestbook-dev` Application imperatively, using the UI. Do you want to manage the Application manifests declaratively too? This is where [the App of Apps pattern](https://youtu.be/2pvGL0zqf9o) comes in. Argo CD can take plain Kubernetes manifests from a directory and deploy them. The `Application` manifests are Kubernetes resources, just like a `Deployment`. Therefore, an Application pointing to a folder in Git containing `Application` manifests will work the same as the `guestbook-dev` Application from earlier. With the caveat that for Argo CD application controller to pick up Applications, they must be created in the `argocd` namespace. 1. Navigate to the Applications dashboard in the Argo CD UI, and click NEW APP. 2. In the top right, click EDIT AS YAML. 3. Paste the contents of `app-of-apps.yaml` (in the repo's root). ```yaml apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: bootstrap namespace: argocd spec: destination: name: in-cluster project: default source: path: apps repoURL: https://github.com//intro-argo-cd-tutorial # Update to your repo URL. targetRevision: HEAD ``` This Application will watch the `apps/` directory in your repo which contains Application manifests for the `guestbook-stg` and `guestbook-prod` instances of the `guestbook` chart, and a new `portal` Helm chart. 4. Click SAVE. 5. Then, in the top left, click CREATE. 6. Click on the Application card titled `argocd/bootstrap`. At this point, the Application will be out-of-sync. The diff will show the addition of the `argocd.argoproj.io/tracking-id` label to the existing `guestbook-dev` Application, which indicates that the "App of Apps now manages it". ```diff kind: Application metadata: ++ annotations: ++ argocd.argoproj.io/tracking-id: 'bootstrap:argoproj.io/Application:argocd/guestbook-dev' generation: 44 labels: ... path: guestbook repoURL: 'https://github.com//intro-argo-cd-tutorial' syncPolicy: automated: {} ``` Along with a new Application for the `portal` Helm chart. 7. To apply the changes, in the top bar, click SYNC then SYNCHRONIZE. From this Application, you can see all of the other Applications managed by it in the resource tree. Each child Application resource has a link to its view on the resource card. ## 5. Tool Detection, and Sync Waves After creating the App-of-Apps it deployed the `portal` Application based on the manifest in Git (`apps/portal.yaml`). Since the automated sync policy is not enabled, it remains out-of-sync. We'll go through some explanation before triggering the sync. 1. Click on the Application card titled `argocd/portal`. ### 5.1. Tool Detection The `portal` `Application` utilizes Kustomize via the `kustomization.yaml` file in the `portal` folder. Unlike the `guestbook-dev` `Application`, the `portal` does not specify Kustomize in the `source` spec. Instead, it relies on Argo CD's automatic tool detection. If a config management tool is not specified in the `source` of an `Application`, Argo CD will check for the following: 1. A `chart.yaml` file in the folder. If found, it will assume that the folder contains a Helm chart. 2. A `kustomization.yaml` file in the folder. If found, Argo CD will use Kustomize. If neither is found, Argo CD will default to plain Kubernetes manifests. Since the `portal` folder contains the `manifests.yaml`, Argo CD knows to use Kubernetes manifests. ### 5.2. Sync Phases, Waves, & Hooks Each time Argo CD performs a sync on an Application, it does not simply generate the manifests and apply them to the cluster. Each sync contains multiple phases and waves. It may also create Kubernetes `Job` resources known as hooks. The `portal` `Application` is an example of this functionality. The `portal` folder contains a `frontend` and `backend` `Deployment` with corresponding `Service`s, and 3 `Jobs`. Yet the resources shown in the out-of-sync `Application` don't contain those `Job`s. This is because the `Job`s contain the `argocd.argoproj.io/hook` annotation which indicates to Argo CD that the resource should applied during a sync. Typically hooks are `Jobs` or (Argo) `Workflows`, but can be any resource. In the `portal` `Application`, hooks are used to update the SQL schema for the backend, and bring up and down a maintenance page for the frontend. The schema update `Job`, runs in the `PreSync` phase which happens before the `Sync` phase when resources are applied. Therefore, before updating the `image` for the `backend` `Deployment`, the schema can be updated in preparation. The `frontend` `Deployment` and related resource hooks rely on sync waves to ensure they are executed in the correct order. Each phase in a sync can contain multiple sync waves. The default sync wave, which all resources that don't specify the `argocd.argoproj.io/sync-wave` fall on, is `0`. Sync waves can be negative, so a wave of `-1` will run before all resources on the default wave. The hook to bring up the maintenance page for the frontend runs on sync wave `1`. The `frontend` `Deployment` and `Service` are on wave `2`. Then the hook to bring down the maintenance page is on wave `3`. This order of waves ensures that the maintenance page is brought up first. While it's up, the changes are made to the frontend resources. Then once their sync is complete, the page is brought back down. ### 5.3. Sync It! With an understanding of how the `portal` `Application` sync works, go ahead and trigger a sync and watch as the resources are created in a precisely choreographed fashion, rather than all at once. 1. In the top bar, click SYNC then SYNCHRONIZE. ## 6. Review You have reached the end of the tutorial. You have an Argo CD instance deploying Helm charts from your repo into your cluster. You no longer manually deploy Helm chart changes. The Application spec describes the process for deploying the Helm charts declaratively. There's no longer a need for direct access to the cluster, removing the primary source of configuration drift. --- ## Introduction to Argo CD on EKS This tutorial will walk you through implementing Argo CD on EKS with the Akuity Platform, to manage the deployment of the Helm charts in a declarative fashion. Ultimately, you will have a Kubernetes cluster, with Applications deployed using an Argo CD control plane. - [1. Prerequisites](#1-prerequisites) - [2. Setting up Your Environment](#2-setting-up-your-environment) - [2.1. Create the Repository from a Template](#21-create-the-repository-from-a-template) - [2.2. Setup `kubectl` Access to EKS](#22-setup-kubectl-access-to-eks) - [2.3. Akuity Platform Sign Up](#23-akuity-platform-sign-up) - [2.4. Setup Access for the `akuity` CLI](#24-setup-access-for-the-akuity-cli) - [2.5. Create your Argo CD Instance](#25-create-your-argo-cd-instance) - [2.5.1. Configure Your Instance](#251-configure-your-instance) - [2.6. Deploy an Agent to the Cluster](#26-deploy-an-agent-to-the-cluster) - [3. Using Argo CD to Deploy Helm Charts](#3-using-argo-cd-to-deploy-helm-charts) - [3.1. Create an Application in Argo CD](#31-create-an-application-in-argo-cd) - [3.2. Syncing Changes Manually](#32-syncing-changes-manually) - [3.3. Enable Auto-sync and Self-heal for the Guestbook Application](#33-enable-auto-sync-and-self-heal-for-the-guestbook-application) - [3.4. Demonstrate Application Auto-sync via Git](#34-demonstrate-application-auto-sync-via-git) - [4. Managing Argo CD Applications Declaratively](#4-managing-argo-cd-applications-declaratively) - [4.1. Create an App of Apps](#41-create-an-app-of-apps) - [5. Tool Detection, and Sync Waves](#5-tool-detection-and-sync-waves) - [5.1. Tool Detection](#51-tool-detection) - [5.2. Sync Phases, Waves, \& Hooks](#52-sync-phases-waves--hooks) - [5.3. Sync It!](#53-sync-it) - [6. Review](#6-review) ## 1. Prerequisites To follow this tutorial make sure you have minimal working knowledge of the following concepts: - [Kubernetes](https://youtu.be/4ht22ReBjno?t=164) - [GitOps](https://akuity.io/gitops) The tutorial requires that you have: - an AWS [EKS cluster](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html). - a [GitHub](https://github.com/) Account. You will use this to: - host a **public** repo for the GitOps configuration. - utilize [GitHub Codespaces](https://github.com/features/codespaces) for the workshop environment. Ensure that you have a quota available. The free tier includes 4 vCPU at 30 hours a month. - create an account on the Akuity Platform. The tutorial was written and tested using the following tool and component versions: - Argo CD: v2.10.1 - Docker Desktop: 4.13.1 - Kubernertes: v1.29.1 - kind: v0.22.0 ## 2. Setting up Your Environment ### 2.1. Create the Repository from a Template In this scenario, you manage the application Helm charts in version control. To represent this in the lab, you will create a repository from a template containing the application Helm charts. 1. Click [this link](https://github.com/akuity/intro-argo-cd-eks-tutorial-template/generate) or click "Use this template" from the [`akuity/intro-argo-cd-eks-tutorial-template`](https://github.com/akuity/intro-argo-cd-eks-tutorial-template) repo main page. 2. Ensure the desired "Owner" is selected (e.g., your account and not an organization). 3. Enter `intro-argo-cd-tutorial` for the "Repository name". 4. Then click Create repository from template. 5. Next, you'll start a new Codespace by clicking the green Code button on the repo page, selecting the Codespaces tab, and then selecting Create codespace on main. The Codespace will open in another browser tab with information about setting up your Codespace. Once it's done setting up, you should see a terminal in the browser with the repo open. ### 2.2. Setup `kubectl` Access to EKS Part of the codespace setup was to install all necessary tools, which includes installing the `aws` and `kubectl` CLIs. However, you'll need to configure the `kubectl` context to access your EKS cluster. 1. [Authenticate the `aws` CLI](https://docs.aws.amazon.com/cli/v1/userguide/cli-chap-authentication.html) in the Codespace. 2. Test that the authentication is working by getting the name of your EKS cluster. ``` aws eks list-clusters ``` You should see output **similar** to the following: ``` { "clusters": [ "eksworkshop-eksctl" ] } ``` 3. [Create a kubeconfig file for your cluster](https://docs.aws.amazon.com/eks/latest/userguide/create-kubeconfig.html) using the following command. ``` aws eks update-kubeconfig --name $(aws eks list-clusters | jq -r .clusters[0]) ``` You should see output **similar** to the following: ``` Added new context arn:aws:eks:us-east-1:338615488317:cluster/ to /home/vscode/.kube/config ``` :::info This command uses some bash-fu, so let's break that down: `$(aws eks list-clusters | jq -r .clusters[0])`: This part of the command is a sub-command enclosed in `$()`, which means it will be executed first, and its output will be used as the value for the `--name` parameter. `aws eks list-clusters`: This AWS CLI command lists all EKS clusters in the current AWS account and region. `|`: The pipe symbol takes the output of the previous command (the list of clusters) and passes it as input to the next command. `jq -r .clusters[0]`: `jq` is a command-line tool for processing JSON. The `-r` option tells `jq` to output raw text instead of JSON-formatted text. The `.clusters[0]` part extracts the first element of the `clusters` array from the JSON output provided by the `aws eks list-clusters` command. ::: 4. Test that `kubectl` can access the cluster. ``` k get nodes ``` You should see output **similar** to the following: ``` NAME STATUS ROLES AGE VERSION ip-192-168-108-33.ec2.internal Ready 2d v1.28.8-eks-ae9a62a ip-192-168-158-117.ec2.internal Ready 2d v1.28.8-eks-ae9a62a ip-192-168-182-251.ec2.internal Ready 2d v1.28.8-eks-ae9a62a ``` ### 2.3. Akuity Platform Sign Up This scenario demonstrates deploying applications to a cluster external to Argo CD. Similar to how the GitHub repo is hosting the Helm charts, which describe **what** resources to deploy into Kubernetes, the Akuity Platform will host the Application manifests, which represent **how** to deploy the resources into the cluster. Along with Argo CD, which will implement the changes on the cluster. :::tip [Sign up](https://training.akuity.cloud/) for a free 30-day trial of the Akuity Platform! ::: 1. Create an account on the [Akuity Platform](https://training.akuity.cloud/). 2. To log in with GitHub SSO, click "Continue with GitHub". :::note You can also use Google SSO or an email and password combination. ::: 3. Click Authorize akuityio. 4. Click the create or join link. 5. Click + New organization in the upper right hand corner of the dashboard. 6. Name your organization following the rules listed below the Organization Name field. ### 2.4. Setup Access for the `akuity` CLI 1. Select the Organization you want to create a key for, from the pull down menu. 2. Switch to the API Keys tab. 2. Click + New Key button on the lower right side of the page. 3. Set the Description for the key to `workshop`. 5. Assign the `Owner` Role to the key. 6. Click the Create button. 7. Click the Copy to Clipboard button, then paste and run the commands in the Codespace terminal. ### 2.5. Create your Argo CD Instance You can create your Argo CD instance using the Akuity Platform **Dashboard or CLI** by choosing between the tabs below. **Dashboard** 7. Navigate to Argo CD. 8. Click + Create in the upper right hand corner of the dashboard. 9. Name your instance following the rules listed below the Instance Name field. 10. (Optionally) Choose the Argo CD version you want to use. 11. Click + Create. At this point, your Argo CD instance will begin initializing. The start-up typically takes under 2 minutes. #### 2.5.1. Configure Your Instance While the instance is initializing, you can prepare it for the rest of the lab. 1. In the dashboard for the Argo CD instance, click Settings. 2. On the inner sidebar, under "Security & Access", click System Accounts. 3. Enable the "Admin Account" by clicking the toggle and clicking Confirm on the prompt. 4. Then, for the `admin` user, click Set Password. 5. Click Regenerate Password, then click Copy. 6. In the bottom right of the Set password prompt, hit Close. 7. In the top, next to the Argo CD instance name and status, click the instance URL (e.g., `.cd.akuity.cloud`) to open the Argo CD login page in a new tab. 8. Enter the username `admin` and the password copied previously. You now have a fully-managed Argo CD instance 🎉 ### 2.6. Deploy an Agent to the Cluster You must connect the cluster to Argo CD to deploy the application resources. The Akuity Platform uses an agent-based architecture for connecting external clusters. So, you will provision an agent and deploy it to the cluster. 1. Back on the Akuity Platform, in the top left of the dashboard for the Argo CD instance, click Clusters. 2. In the top right, click Connect a cluster. 3. Enter the `eks` name as the "Cluster Name". 4. In the bottom right, click Connect Cluster. 5. To get the agent install command, click Copy to Clipboard. Then, in the bottom right, Done. 6. Open your terminal and check that your target is the correct cluster by running `kubectl config current-context`. You should see output **similar** to the following: ``` arn:aws:eks:us-east-1:338615488317:cluster/ ``` 7. Paste and run the command against the cluster. The command will create the `akuity` namespace and deploy the resources for the Akuity Agent. 8. Check the pods in the `akuity` namespace. Wait for the `Running` status on all pods (approx. 1 minute). ``` % kubectl get pods -n akuity NAME READY STATUS RESTARTS AGE akuity-agent-- 1/1 Running 0 65s akuity-agent-- 1/1 Running 0 65s argocd-application-controller-- 2/2 Running 0 65s argocd-notifications-controller-- 1/1 Running 0 65s argocd-redis-- 1/1 Running 0 65s argocd-repo-server-- 1/1 Running 0 64s argocd-repo-server-- 1/1 Running 0 64s ``` Re-run the `kubectl get pods -n akuity` command to check for updates on the pod statuses. 9. Back on the Clusters dashboard, confirm that the cluster shows a green heart before the name, indicating a healthy status. **CLI** 1. Set your organization name in the `akuity` config ``` akuity config set --organization-id=$(akuity org list | awk 'NR==2 {print $1}') ``` :::info This command uses some bash-fu, so let's break that down: `$(akuity org list | awk 'NR==2 {print $1}')`: This part of the command is a sub-command enclosed in `$()`, which means it will be executed first, and its output will be used as the value for the `--organization-id` parameter. `akuity org list`: This command lists all organizations in your Akuity Platform account. In this case, there should only be one. `|`: The pipe symbol takes the output of the previous command (the list of organizations) and passes it as input to the next command. `awk 'NR==2 {print $1}'`: `awk` is a text processing tool. This specific awk command is used to extract the first field (`$1`) from the second line (`NR==2`) of the input provided by the `akuity org list` command. ::: 2. Create the Argo CD instance on the Akuity Platform ``` akuity argocd apply -f akuity-platform/ ``` 3. Apply the agent install manifests to the cluster. ``` akuity argocd cluster get-agent-manifests --instance-name=argo-cd eks | kubectl apply -f - ``` 4. From the Akuity Platform Dashboard, in the top, next to the Argo CD instance name and status, click the instance URL (e.g., `.cd.akuity.cloud`) to open the Argo CD login page in a new tab. 5. Enter the username `admin` and the password `akuity-argocd`. You now have a fully-managed Argo CD instance 🎉 ## 3. Using Argo CD to Deploy Helm Charts ### 3.1. Create an Application in Argo CD Now, using an Application, you will declaratively tell Argo CD how to deploy the Helm charts. Start by creating an Application to deploy the `guestbook` Helm Chart from the repo. **Dashboard** 1. Navigate to the Argo CD UI, and click NEW APP. 2. In the top right, click EDIT AS YAML. 3. Paste the contents of `apps/guestbook-dev.yaml` from your repo. :::info This manifest describes an Application. - The name of the Application is `guestbook-dev`. - The source is your repo with the Helm charts. - The destination is the cluster connected by the agent. - The sync policy will automatically create the namespace. ::: 4. Click SAVE. At this point, the UI has translated the Application manifest into the corresponding fields in the wizard. 5. In the top left, click CREATE. The new app pane will close and show the card for the Application you created. The status on the card will show "Missing" and "OutOfSync". 6. Click on the Application card titled `argocd/guestbook-dev`. :::info In this state, the Application resource tree shows the manifests generated from the source repo URL and path defined. You can click DIFF to see what manifests the Application rendered. Since auto-sync is disabled, the resources do not exist in the destination yet. ::: 7. In the top bar, click SYNC then SYNCHRONIZE to instruct Argo CD to create the resources defined by the Application. The resource tree will expand as the Deployment creates a ReplicaSet that makes a pod, and the Service creates an Endpoint and EndpointSlice. The Application will remain in the "Progressing" state until the pod for the deployment is running. Afterwards, all the top-level resources (i.e., those rendered from the Application source) in the tree will show a green checkmark, indicating that they are synced (i.e., present in the cluster). **CLI** Coming soon. ### 3.2. Syncing Changes Manually An Application now manages the deployment of the `guestbook` Helm chart. So what happens when you want to deploy a new image tag? Instead of running `helm upgrade guestbook-dev ./guestbook`, you will trigger a sync of the Application. 1. Navigate to your repo on GitHub, and open the file `guestbook/values-dev.yaml`. 2. In the top right of the file, click the pencil icon to edit. 3. Override the default `image.tag` value by setting it to `0.2.0`. ```yaml image: tag: 0.2.0 ``` 4. Click Commit changes.... 5. Add a commit message. For example `chore(guestbook): bump dev tag to 0.2.0`. 6. Click Commit changes. 7. Switch to the Argo CD UI and go to the `argocd/guestbook-dev` Application. 8. In the top right, click the REFRESH button to trigger Argo CD to check for any changes to the Application source and resources. :::note The default sync interval is 3 minutes. Any changes made in Git may not apply for up to 3 minutes. ::: 9. In the top bar, click SYNC then SYNCHRONIZE to instruct Argo CD to deploy the changes. Due to the change in the repo, Argo CD will detect that the Application is out-of-sync. It will template the Helm chart (i.e., `helm template`) and patch the `guestbook-dev` deployment with the new image tag, triggering a rolling update. ### 3.3. Enable Auto-sync and Self-heal for the Guestbook Application Now that you are using an Application to describe how to deploy the Helm chart into the cluster, you can configure the sync policy to automatically apply changes — removing the need for developers to manually trigger a deployment for changes that already made it through the approval processes. 1. In the top menu, click DETAILS. 2. Under the SYNC POLICY section, click ENABLE AUTO-SYNC and on the prompt, click OK. 3. Below that, on the right of "SELF HEAL", click ENABLE. 4. In the top right of the DETAILS pane, click the X to close it. If the Application was out-of-sync, this would immediately trigger a sync. In this case, your Application is already in sync, so Argo CD made no changes. ### 3.4. Demonstrate Application Auto-sync via Git With auto-sync enabled on the `guestbook-dev` Application, changes made to the `main` branch in the repo will be applied automatically to the cluster. You will demonstrate this by updating the number of replicas for the `guestbook-dev` deployment. 1. Navigate to your repo on Github, and open the file `guestbook/values.yaml`. 2. In the top right of the file, click the pencil icon to edit. 3. Update the `replicaCount` to the `2` list. 4. In the top right, click Commit changes.... 5. Add a commit message. For example `chore(guestbook): scale to 2 replicas`. 6. In the bottom left, click Commit changes. 7. Switch to the Argo CD UI and go to the `argocd/guestbook-dev` Application. 8. In the top right, click the REFRESH button to trigger Argo CD to check for any changes to the Application source and resources. You can view the details of the sync operation by, in the top menu, clicking SYNC STATUS. Here it will display, what "REVISION" it was for, what triggered it (i.e., "INITIATED BY: automated sync policy"), and the result of the sync (i.e., what resources changed). {/* ### 3.5. Demonstrate Application Self-heal Functionality In your organization, everyone has direct and privileged access to the cluster. Users may apply changes to the cluster outside of the repo due to the over-provisioned access. For example, applying a Helm chart change to the cluster without getting pushed to the repo first. With self-heal enabled, Argo CD will reconcile any changes to the Application resources that deviate from the repo. To demonstrate this: 1. From the `guestbook` Application page in the Argo CD UI: 2. Locate the `guestbook` deploy (i.e., Deployment) resource and click the three vertical dots on the right side of the card. 3. Then click Delete. 4. Enter the deployment name `guestbook` and click OK. Almost as quickly as you delete it, Argo CD will detect that the deploy resource is missing from the Application. It will briefly display the yellow circle with a white arrow to indicate that the resource is out-of-sync. Then automatically recreate it, bringing the Application back to a healthy status. */} ## 4. Managing Argo CD Applications Declaratively ### 4.1. Create an App of Apps One of the benefits of using Argo CD is that you are now codifying the deployment process for the Helm charts in the Application spec. Earlier in the lab, you created the `guestbook-dev` Application imperatively, using the UI. Do you want to manage the Application manifests declaratively too? This is where [the App of Apps pattern](https://youtu.be/2pvGL0zqf9o) comes in. Argo CD can take plain Kubernetes manifests from a directory and deploy them. The `Application` manifests are Kubernetes resources, just like a `Deployment`. Therefore, an Application pointing to a folder in Git containing `Application` manifests will work the same as the `guestbook-dev` Application from earlier. With the caveat that for Argo CD application controller to pick up Applications, they must be created in the `argocd` namespace. 1. Navigate to the Applications dashboard in the Argo CD UI, and click NEW APP. 2. In the top right, click EDIT AS YAML. 3. Paste the contents of `app-of-apps.yaml` (in the repo's root). ```yaml apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: bootstrap namespace: argocd spec: destination: name: in-cluster project: default source: path: apps repoURL: https://github.com//intro-argo-cd-tutorial # Update to your repo URL. targetRevision: HEAD ``` This Application will watch the `apps/` directory in your repo which contains Application manifests for the `guestbook-stg` and `guestbook-prod` instances of the `guestbook` chart, and a new `portal` Helm chart. 4. Click SAVE. 5. Then, in the top left, click CREATE. 6. Click on the Application card titled `argocd/bootstrap`. At this point, the Application will be out-of-sync. The diff will show the addition of the `argocd.argoproj.io/tracking-id` label to the existing `guestbook-dev` Application, which indicates that the "App of Apps now manages it". ```diff kind: Application metadata: ++ annotations: ++ argocd.argoproj.io/tracking-id: 'bootstrap:argoproj.io/Application:argocd/guestbook-dev' generation: 44 labels: ... path: guestbook repoURL: 'https://github.com//intro-argo-cd-eks-tutorial' syncPolicy: automated: {} ``` Along with a new Application for the `portal` Helm chart. 7. To apply the changes, in the top bar, click SYNC then SYNCHRONIZE. From this Application, you can see all of the other Applications managed by it in the resource tree. Each child Application resource has a link to its view on the resource card. ## 5. Tool Detection, and Sync Waves After creating the App-of-Apps it deployed the `portal` Application based on the manifest in Git (`apps/portal.yaml`). Since the automated sync policy is not enabled, it remains out-of-sync. We'll go through some explanation before triggering the sync. 1. Click on the Application card titled `argocd/portal`. ### 5.1. Tool Detection The `portal` `Application` utilizes Kustomize via the `kustomization.yaml` file in the `portal` folder. Unlike the `guestbook-dev` `Application`, the `portal` does not specify Kustomize in the `source` spec. Instead, it relies on Argo CD's automatic tool detection. If a config management tool is not specified in the `source` of an `Application`, Argo CD will check for the following: 1. A `chart.yaml` file in the folder. If found, it will assume that the folder contains a Helm chart. 2. A `kustomization.yaml` file in the folder. If found, Argo CD will use Kustomize. If neither is found, Argo CD will default to plain Kubernetes manifests. Since the `portal` folder contains the `kustomization.yaml`, Argo CD knows to use Kustomize. ### 5.2. Sync Phases, Waves, & Hooks Each time Argo CD performs a sync on an Application, it does not simply generate the manifests and apply them to the cluster. Each sync contains multiple phases and waves. It may also create Kubernetes `Job` resources known as hooks. The `portal` `Application` is an example of this functionality. The `portal` folder contains a `frontend` and `backend` `Deployment` with corresponding `Service`s, and 3 `Jobs`. Yet the resources shown in the out-of-sync `Application` don't contain those `Job`s. This is because the `Job`s contain the `argocd.argoproj.io/hook` annotation which indicates to Argo CD that the resource should applied during a sync. Typically hooks are `Jobs` or (Argo) `Workflows`, but can be any resource. In the `portal` `Application`, hooks are used to update the SQL schema for the backend, and bring up and down a maintenance page for the frontend. The schema update `Job`, runs in the `PreSync` phase which happens before the `Sync` phase when resources are applied. Therefore, before updating the `image` for the `backend` `Deployment`, the schema can be updated in preparation. The `frontend` `Deployment` and related resource hooks rely on sync waves to ensure they are executed in the correct order. Each phase in a sync can contain multiple sync waves. The default sync wave, which all resources that don't specify the `argocd.argoproj.io/sync-wave` fall on, is `0`. Sync waves can be negative, so a wave of `-1` will run before all resources on the default wave. The hook to bring up the maintenance page for the frontend runs on sync wave `1`. The `frontend` `Deployment` and `Service` are on wave `2`. Then the hook to bring down the maintenance page is on wave `3`. This order of waves ensures that the maintenance page is brought up first. While it's up, the changes are made to the frontend resources. Then once their sync is complete, the page is brought back down. ### 5.3. Sync It! With an understanding of how the `portal` `Application` sync works, go ahead and trigger a sync and watch as the resources are created in a precisely choreographed fashion, rather than all at once. 1. In the top bar, click SYNC then SYNCHRONIZE. ## 6. Review You have reached the end of the tutorial. You have an Argo CD instance deploying Helm charts from your repo into your cluster. You no longer manually deploy Helm chart changes. The Application spec describes the process for deploying the Helm charts declaratively. There's no longer a need for direct access to the cluster, removing the primary source of configuration drift. --- ## Introduction to Argo CD for FinTech This tutorial will walk you through building container images with GitHub Actions, and then implementing Argo CD with the Akuity Platform, to manage the deployment of the container to Kubernetes using Helm charts and GitOps. Ultimately, you will have a Kubernetes cluster, with Applications deployed using an Argo CD control plane. - [1. Prerequisites](#1-prerequisites) - [2. Setting up Your Environment](#2-setting-up-your-environment) - [2.1. Create the Repository from a Template](#21-create-the-repository-from-a-template) - [2.1.1. Verify Environment](#211-verify-environment) - [2.2. Akuity Platform Sign Up](#22-akuity-platform-sign-up) - [2.3. Setup Access for the `akuity` CLI](#23-setup-access-for-the-akuity-cli) - [2.4. Create your Argo CD Instance](#24-create-your-argo-cd-instance) - [2.4.1. Configure Your Instance](#241-configure-your-instance) - [2.5. Deploy an Agent to the Cluster](#25-deploy-an-agent-to-the-cluster) - [3. Building a Container Image with GitHub Actions](#3-building-a-container-image-with-github-actions) - [Creating Your Container Image](#creating-your-container-image) - [Using Your Container Image](#using-your-container-image) - [4. Using Argo CD to Deploy Helm Charts](#4-using-argo-cd-to-deploy-helm-charts) - [4.1. Create an Application in Argo CD](#41-create-an-application-in-argo-cd) - [4.2. Syncing Changes Manually](#42-syncing-changes-manually) - [Trigger a new container build](#trigger-a-new-container-build) - [Using the container image](#using-the-container-image) - [4.3. Enable Auto-sync and Self-heal for the Guestbook Application](#43-enable-auto-sync-and-self-heal-for-the-guestbook-application) - [4.4. Demonstrate Application Auto-sync via Git](#44-demonstrate-application-auto-sync-via-git) - [5. Managing Argo CD Applications Declaratively](#5-managing-argo-cd-applications-declaratively) - [5.1. Create an App of Apps](#51-create-an-app-of-apps) - [6. Tool Detection, and Sync Waves](#6-tool-detection-and-sync-waves) - [6.1. Tool Detection](#61-tool-detection) - [6.2. Sync Phases, Waves, \& Hooks](#62-sync-phases-waves--hooks) - [6.3. Sync It!](#63-sync-it) - [7. Review](#7-review) ## 1. Prerequisites To follow this tutorial make sure you have minimal working knowledge of the following concepts: - [Kubernetes](https://youtu.be/4ht22ReBjno?t=164) The tutorial requires that you also have a [GitHub](https://github.com/) Account. You will use this to: - host a **public** repo for the GitOps configuration. - utilize [GitHub Codespaces](https://github.com/features/codespaces) for the workshop environment. Ensure that you have a quota available. The free tier includes 4 vCPU at 30 hours a month. - create an account on the Akuity Platform. The tutorial was written and tested using the following tool and component versions: - Argo CD: v2.10.1 - Docker Desktop: 4.13.1 - Kubernertes: v1.29.1 - k3s: v5.6.3 ## 2. Setting up Your Environment ### 2.1. Create the Repository from a Template In this scenario, you will utilize GitHub to host the Git repo containing the Kubernetes manifests and building a container image. To represent this in the workshop, you will create a repository from a template. 1. Click [this link](https://github.com/akuity/intro-argo-cd-tutorial-template/generate) or click "Use this template" from the [`akuity/intro-argo-cd-tutorial-template`](https://github.com/akuity/intro-argo-cd-tutorial-template) repo main page. 2. Ensure the desired "Owner" is selected (e.g., your account and not an organization). 3. Enter `intro-argo-cd` for the "Repository name". 4. Then click Create repository from template. 5. Next, you'll start a new Codespace by clicking the green Code button on the repo page, selecting the Codespaces tab, and then selecting Create codespace on main. The Codespace will open in another browser tab with information about setting up your codespace. Once it's done setting up, you should see a terminal in the browser with the repo open. #### 2.1.1. Verify Environment Part of the codespace setup was to install all necessary tools, which includes setting up `k3d` and `kubectl`. You can verify that the environment is ready by going through the following: 1. Verify that `k3d` is installed and running a Kubernetes cluster. ``` k3d cluster list ``` You should see the following output: ``` NAME SERVERS AGENTS LOADBALANCER dev 1/1 0/0 true ``` 2. Check that the cluster works by running `kubectl get nodes`. ``` % kubectl get nodes NAME STATUS ROLES AGE VERSION dev-control-plane Ready control-plane 7m44s v1.29.2 ``` Fetching the nodes will demonstrate that `kubectl` can connect to the cluster and query the API server. The node should be in the "Ready" status. ### 2.2. Akuity Platform Sign Up This scenario demonstrates deploying applications to a cluster external to Argo CD. Similar to how the GitHub repo is hosting the Helm charts, which describe **what** resources to deploy into Kubernetes, the Akuity Platform will host the Application manifests, which represent **how** to deploy the resources into the cluster. Along with Argo CD, which will implement the changes on the cluster. :::tip [Sign up](https://training.akuity.cloud/) for a free 30-day trial of the Akuity Platform! ::: 1. Create an account on the [Akuity Platform](https://training.akuity.cloud/). 2. To log in with GitHub SSO, click "Continue with GitHub". :::note You can also use Google SSO or an email and password combo. ::: 3. Click Authorize akuityio. 4. Click the create or join link. 5. Click + New organization in the upper right hand corner of the dashboard. 6. Name your organization following the rules listed below the Organization Name field. ### 2.3. Setup Access for the `akuity` CLI 1. Select the Organization you want to create a key for, from the pull down menu. 2. Switch to the API Keys tab. 2. Click + New Key button on the lower right side of the page. 3. Set the Description for the key to `workshop`. 5. Assign the `Owner` Role to the key. 6. Click the Create button. 7. Click the Copy to Clipboard button, then paste and run the commands in the Codespace terminal. ### 2.4. Create your Argo CD Instance You can create your Argo CD instance using the Akuity Platform **Dashboard or CLI** by choosing between the tabs below. **CLI** 1. Set your organization name in the `akuity` config ``` akuity config set --organization-id=$(akuity org list | awk 'NR==2 {print $1}') ``` :::info This command uses some bash-fu, so let's break that down: `$(akuity org list | awk 'NR==2 {print $1}')`: This part of the command is a sub-command enclosed in `$()`, which means it will be executed first, and its output will be used as the value for the `--organization-id` parameter. `akuity org list`: This command lists all organizations in your Akuity Platform account. In this case, there should only be one. `|`: The pipe symbol takes the output of the previous command (the list of organizations) and passes it as input to the next command. `awk 'NR==2 {print $1}'`: `awk` is a text processing tool. This specific awk command is used to extract the first field (`$1`) from the second line (`NR==2`) of the input provided by the `akuity org list` command. ::: 2. Create the Argo CD instance on the Akuity Platform ``` akuity argocd apply -f akuity-platform/ ``` 3. Wait for the instance to become healthy, then apply the agent install manifests to the cluster. ``` akuity argocd cluster get-agent-manifests --instance-name=argo-cd dev | kubectl apply -f - ``` 4. From the Akuity Platform Dashboard, in the top, next to the Argo CD instance name and status, click the instance URL (e.g., `.cd.akuity.cloud`) to open the Argo CD login page in a new tab. 5. Enter the username `admin` and the password `akuity-argocd`. You now have a fully-managed Argo CD instance 🎉 **Dashboard** 7. Navigate to Argo CD. 8. Click + Create in the upper right hand corner of the dashboard. 9. Name your instance following the rules listed below the Instance Name field. 10. (Optionally) Choose the Argo CD version you want to use. 11. Click + Create. At this point, your Argo CD instance will begin initializing. The start-up typically takes under 2 minutes. #### 2.4.1. Configure Your Instance While the instance is initializing, you can prepare it for the rest of the lab. 1. In the dashboard for the Argo CD instance, click Settings. 2. On the inner sidebar, under "Security & Access", click System Accounts. 3. Enable the "Admin Account" by clicking the toggle and clicking Confirm on the prompt. 4. Then, for the `admin` user, click Set Password. 5. Click Regenerate Password, then click Copy. 6. In the bottom right of the Set password prompt, hit Close. 7. In the top, next to the Argo CD instance name and status, click the instance URL (e.g., `.cd.akuity.cloud`) to open the Argo CD login page in a new tab. 8. Enter the username `admin` and the password copied previously. You now have a fully-managed Argo CD instance 🎉 ### 2.5. Deploy an Agent to the Cluster You must connect the cluster to Argo CD to deploy the application resources. The Akuity Platform uses an agent-based architecture for connecting external clusters. So, you will provision an agent and deploy it to the cluster. 1. Back on the Akuity Platform, in the top left of the dashboard for the Argo CD instance, click Clusters. 2. In the top right, click Connect a cluster. 3. Enter the `dev` name as the "Cluster Name". 4. In the bottom right, click Connect Cluster. 5. To get the agent install command, click Copy to Clipboard. Then, in the bottom right, Done. 6. Open your terminal and check that your target is the correct cluster by running `kubectl config current-context`. If you are following along using `k3d`, you should see the following: ``` % kubectl config current-context k3d-dev ``` 7. Paste and run the command against the cluster. The command will create the `akuity` namespace and deploy the resources for the Akuity Agent. 8. Check the pods in the `akuity` namespace. Wait for the `Running` status on all pods (approx. 1 minute). ``` % kubectl get pods -n akuity NAME READY STATUS RESTARTS AGE akuity-agent-- 1/1 Running 0 65s akuity-agent-- 1/1 Running 0 65s argocd-application-controller-- 2/2 Running 0 65s argocd-notifications-controller-- 1/1 Running 0 65s argocd-redis-- 1/1 Running 0 65s argocd-repo-server-- 1/1 Running 0 64s argocd-repo-server-- 1/1 Running 0 64s ``` Re-run the `kubectl get pods -n akuity` command to check for updates on the pod statuses. 9. Back on the Clusters dashboard, confirm that the cluster shows a green heart before the name, indicating a healthy status. ## 3. Building a Container Image with GitHub Actions ### Creating Your Container Image The goal of continuous delivery is to react to new releases (versions) of applications and deploy them to the desired location. For the sake of this workshop, you'll use a simplified example of building a container image, which you will later deploy to Kubernetes following GitOps principles with Argo CD. The repository that you cloned contains a `Dockerfile` at the root. The file itself is rather simple, it takes an existing container image as the base and builds a new container from it. The `Dockerfile` is purely illustrative, representing what would normally be a more complex set of instructions that generate an image based on source files. In the context of the workshop, the `Dockerfile` is used to build custom container images for deployment into your Kubernetes cluster. ```Dockerfile FROM quay.io/akuity/argo-cd-learning-assets/guestbook:latest ``` The `.github/workflows` folder contains a workflow file `build.yaml` used to build an image based on the `Dockerfile` and push it to the GitHub Container Registry (GHCR) associated with the repository. The workflow is configured to push a new image for each change that includes the `Dockerfile`, tagging it with `latest` and the first 7 characters of the commit SHA (e.g. `fe68a20`). ### Using Your Container Image To take advantage of the container image built by GitHub Actions after modifying the `Dockerfile`, you must update the Helm chart to reference it. 1. Navigate to the `guestbook/values.yaml` file in your repository. 2. In a separate tab, open the package (container image in GHCR) associated with your repo. ![GHCR Package on the repo main page](./ghcr-packages.png) 3. Copy the container image repo address and paste it into the `image.repository` value for the Helm chart. ![GHCR Package page](./ghcr-image-repo.png) 4. Commit and push the change to the repo. ## 4. Using Argo CD to Deploy Helm Charts ### 4.1. Create an Application in Argo CD Now, using an Application, you will declaratively tell Argo CD how to deploy the Helm charts. Start by creating an Application to deploy the `guestbook` Helm Chart from the repo. **Dashboard** 1. Navigate to the Argo CD UI, and click NEW APP. 2. In the top right, click EDIT AS YAML. 3. Paste the contents of `apps/guestbook-dev.yaml` from your repo. :::info This manifest describes an Application. - The name of the Application is `guestbook-dev`. - The source is your repo with the Helm charts. - The destination is the cluster connected by the agent. - The sync policy will automatically create the namespace. ::: 4. Click SAVE. At this point, the UI has translated the Application manifest into the corresponding fields in the wizard. 5. In the top left, click CREATE. The new app pane will close and show the card for the Application you created. The status on the card will show "Missing" and "OutOfSync". 6. Click on the Application card titled `argocd/guestbook-dev`. :::info In this state, the Application resource tree shows the manifests generated from the source repo URL and path defined. You can click DIFF to see what manifests the Application rendered. Since auto-sync is disabled, the resources do not exist in the destination yet. ::: 7. In the top bar, click SYNC then SYNCHRONIZE to instruct Argo CD to create the resources defined by the Application. The resource tree will expand as the Deployment creates a ReplicaSet that makes a pod, and the Service creates an Endpoint and EndpointSlice. The Application will remain in the "Progressing" state until the pod for the deployment is running. Afterwards, all the top-level resources (i.e., those rendered from the Application source) in the tree will show a green checkmark, indicating that they are synced (i.e., present in the cluster). ### 4.2. Syncing Changes Manually #### Trigger a new container build To trigger the build of the container image and push to your GHCR, modify the tag in the `FROM` statement in the `Dockerfile` from `latest` to `0.1.0` then commit and push the change. ```diff -- FROM quay.io/akuity/argo-cd-learning-assets/guestbook:latest ++ FROM quay.io/akuity/argo-cd-learning-assets/guestbook:0.1.0 ``` Pushing the commit with the change will trigger the `build` GitHub Actions workflow on your repository, generating the package (container image) in your GHCR. #### Using the container image An Application now manages the deployment of the `guestbook` Helm chart. So what happens when you want to deploy a new image tag? Instead of running `helm upgrade guestbook-dev ./guestbook`, you will trigger a sync of the Application. 1. Navigate to your repo on GitHub, and open the file `guestbook/values-dev.yaml`. 2. In the top right of the file, click the pencil icon to edit. 3. Override the default `image.tag` value by setting it to the newest tag on your package. ```yaml image: tag: ``` 4. Click Commit changes.... 5. Add a commit message. For example `chore(guestbook): bump dev tag`. 6. Click Commit changes. 7. Switch to the Argo CD UI and go to the `argocd/guestbook-dev` Application. 8. In the top right, click the REFRESH button to trigger Argo CD to check for any changes to the Application source and resources. :::note The default sync interval is 3 minutes. Any changes made in Git may not apply for up to 3 minutes. ::: 9. In the top bar, click SYNC then SYNCHRONIZE to instruct Argo CD to deploy the changes. Due to the change in the repo, Argo CD will detect that the Application is out-of-sync. It will template the Helm chart (i.e., `helm template`) and patch the `guestbook-dev` deployment with the new image tag, triggering a rolling update. ### 4.3. Enable Auto-sync and Self-heal for the Guestbook Application Now that you are using an Application to describe how to deploy the Helm chart into the cluster, you can configure the sync policy to automatically apply changes — removing the need for developers to manually trigger a deployment for changes that already made it through the approval processes. 1. In the top menu, click DETAILS. 2. Under the SYNC POLICY section, click ENABLE AUTO-SYNC and on the prompt, click OK. 3. Below that, on the right of "SELF HEAL", click ENABLE. 4. In the top right of the DETAILS pane, click the X to close it. If the Application was out-of-sync, this would immediately trigger a sync. In this case, your Application is already in sync, so Argo CD made no changes. ### 4.4. Demonstrate Application Auto-sync via Git With auto-sync enabled on the `guestbook-dev` Application, changes made to the `main` branch in the repo will be applied automatically to the cluster. You will demonstrate this by updating the number of replicas for the `guestbook-dev` deployment. 1. Navigate to your repo on Github, and open the file `guestbook/values.yaml`. 2. In the top right of the file, click the pencil icon to edit. 3. Update the `replicaCount` to the `2` list. 4. In the top right, click Commit changes.... 5. Add a commit message. For example `chore(guestbook): scale to 2 replicas`. 6. In the bottom left, click Commit changes. 7. Switch to the Argo CD UI and go to the `argocd/guestbook-dev` Application. 8. In the top right, click the REFRESH button to trigger Argo CD to check for any changes to the Application source and resources. You can view the details of the sync operation by, in the top menu, clicking SYNC STATUS. Here it will display, what "REVISION" it was for, what triggered it (i.e., "INITIATED BY: automated sync policy"), and the result of the sync (i.e., what resources changed). ## 5. Managing Argo CD Applications Declaratively ### 5.1. Create an App of Apps One of the benefits of using Argo CD is that you are now codifying the deployment process for the Helm charts in the Application spec. Earlier in the lab, you created the `guestbook-dev` Application imperatively, using the UI. Do you want to manage the Application manifests declaratively too? This is where [the App of Apps pattern](https://youtu.be/2pvGL0zqf9o) comes in. Argo CD can take plain Kubernetes manifests from a directory and deploy them. The `Application` manifests are Kubernetes resources, just like a `Deployment`. Therefore, an Application pointing to a folder in Git containing `Application` manifests will work the same as the `guestbook-dev` Application from earlier. With the caveat that for Argo CD application controller to pick up Applications, they must be created in the `argocd` namespace. 1. Navigate to the Applications dashboard in the Argo CD UI, and click NEW APP. 2. In the top right, click EDIT AS YAML. 3. Paste the contents of `app-of-apps.yaml` (in the repo's root). ```yaml apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: bootstrap namespace: argocd spec: destination: name: in-cluster project: default source: path: apps repoURL: https://github.com/ targetRevision: HEAD ``` This Application will watch the `apps/` directory in your repo which contains Application manifests for the `guestbook-stg` and `guestbook-prod` instances of the `guestbook` chart, and a new `portal` Helm chart. 4. Click SAVE. 5. Then, in the top left, click CREATE. 6. Click on the Application card titled `argocd/bootstrap`. At this point, the Application will be out-of-sync. The diff will show the addition of the `argocd.argoproj.io/tracking-id` label to the existing `guestbook-dev` Application, which indicates that the "App of Apps now manages it". ```diff kind: Application metadata: ++ annotations: ++ argocd.argoproj.io/tracking-id: 'bootstrap:argoproj.io/Application:argocd/guestbook-dev' generation: 44 labels: ... path: guestbook repoURL: 'https://github.com//intro-argo-cd-tutorial' syncPolicy: automated: {} ``` Along with a new Application for the `portal` Helm chart. 7. To apply the changes, in the top bar, click SYNC then SYNCHRONIZE. From this Application, you can see all of the other Applications managed by it in the resource tree. Each child Application resource has a link to its view on the resource card. ## 6. Tool Detection, and Sync Waves After creating the App-of-Apps it deployed the `portal` Application based on the manifest in Git (`apps/portal.yaml`). Since the automated sync policy is not enabled, it remains out-of-sync. We'll go through some explanation before triggering the sync. 1. Click on the Application card titled `argocd/portal`. ### 6.1. Tool Detection The `portal` `Application` utilizes Kustomize via the `kustomization.yaml` file in the `portal` folder. Unlike the `guestbook-dev` `Application`, the `portal` does not specify Kustomize in the `source` spec. Instead, it relies on Argo CD's automatic tool detection. If a config management tool is not specified in the `source` of an `Application`, Argo CD will check for the following: 1. A `chart.yaml` file in the folder. If found, it will assume that the folder contains a Helm chart. 2. A `kustomization.yaml` file in the folder. If found, Argo CD will use Kustomize. If neither is found, Argo CD will default to plain Kubernetes manifests. Since the `portal` folder contains the `manifests.yaml`, Argo CD knows to use Kubernetes manifests. ### 6.2. Sync Phases, Waves, & Hooks Each time Argo CD performs a sync on an Application, it does not simply generate the manifests and apply them to the cluster. Each sync contains multiple phases and waves. It may also create Kubernetes `Job` resources known as hooks. The `portal` `Application` is an example of this functionality. The `portal` folder contains a `frontend` and `backend` `Deployment` with corresponding `Service`s, and 3 `Jobs`. Yet the resources shown in the out-of-sync `Application` don't contain those `Job`s. This is because the `Job`s contain the `argocd.argoproj.io/hook` annotation which indicates to Argo CD that the resource should applied during a sync. Typically hooks are `Jobs` or (Argo) `Workflows`, but can be any resource. In the `portal` `Application`, hooks are used to update the SQL schema for the backend, and bring up and down a maintenance page for the frontend. The schema update `Job`, runs in the `PreSync` phase which happens before the `Sync` phase when resources are applied. Therefore, before updating the `image` for the `backend` `Deployment`, the schema can be updated in preparation. The `frontend` `Deployment` and related resource hooks rely on sync waves to ensure they are executed in the correct order. Each phase in a sync can contain multiple sync waves. The default sync wave, which all resources that don't specify the `argocd.argoproj.io/sync-wave` fall on, is `0`. Sync waves can be negative, so a wave of `-1` will run before all resources on the default wave. The hook to bring up the maintenance page for the frontend runs on sync wave `1`. The `frontend` `Deployment` and `Service` are on wave `2`. Then the hook to bring down the maintenance page is on wave `3`. This order of waves ensures that the maintenance page is brought up first. While it's up, the changes are made to the frontend resources. Then once their sync is complete, the page is brought back down. ### 6.3. Sync It! With an understanding of how the `portal` `Application` sync works, go ahead and trigger a sync and watch as the resources are created in a precisely choreographed fashion, rather than all at once. 1. In the top bar, click SYNC then SYNCHRONIZE. ## 7. Review You have reached the end of the tutorial. You have an Argo CD instance deploying Helm charts from your repo into your cluster. You no longer manually deploy Helm chart changes. The Application spec describes the process for deploying the Helm charts declaratively. There's no longer a need for direct access to the cluster, removing the primary source of configuration drift. --- ## Advanced GitOps Workshop from Akuity # Advanced GitOps Workshop - Advanced GitOps Workshop - [1. Overview](#1-overview) - [1.1. Prerequisites](#11-prerequisites) - [2. Repositories](#2-repositories) - [2.1. Automated Repository Setup](#21-automated-repository-setup) - [2.2. Building Images](#22-building-images) - [3. Argo CD Setup](#3-argo-cd-setup) - [3.1. Creating an Argo CD Instance](#31-creating-an-argo-cd-instance) - [4. Cluster Bootstrapping](#4-cluster-bootstrapping) - [4.1. Automating `Application` Creation with `ApplicationSet`s](#41-automating-application-creation-with-applicationsets) - [4.2. Bootstrapping with App of Apps](#42-bootstrapping-with-app-of-apps) - [5. Self-service Teams](#5-self-service-teams) - [5.1. Creating a Team Environment](#51-creating-a-team-environment) - [6. Rendered Manifests](#6-rendered-manifests) - [6.1. Adding Render Manifests to the `demo-app-deploy` Repo](#61-adding-render-manifests-to-the-demo-app-deploy-repo) - [7. Automating Image Tag Updates](#7-automating-image-tag-updates) - [7.1. Automating the `dev` Environment](#71-automating-the-dev-environment) - [7.2. Automating Promotion to `stage` and `prod`](#72-automating-promotion-to-stage-and-prod) - [8. Summary](#8-summary) - [9. Clean Up](#9-clean-up) - [10. Bonus Question Answers](#10-bonus-question-answers) ## 1. Overview The Advanced GitOps tutorial, presented by [Akuity](https://akuity.io), will take you through creating a self-service multi-tenant Kubernetes environment using Argo CD and GitHub Actions. The tutorial will cover the following topics: - Automating `Application` generation using `ApplicationSet`s. - Using GitHub for Single Sign-on (SSO). - Managing manifests for promotion between environments. - Enabling self-service environment creation for teams. Naturally, the Argo CD configuration is managed by the cluster administrators. However, developers will not need administrators to create their environments. With GitOps, teams can self-onboard, leveraging Helm Charts provided by the administrators to abstract the resources that comprise an environment and pull requests to propose the creation of and changes to them. ### 1.1. Prerequisites The tutorial assumes you have experience working with Kubernetes, GitOps, GitHub Actions (or a similar CI engine), and Argo CD. Given such, some underlying concepts won't be explained during this tutorial. The tutorial requires that you have the following: - a **dedicated Kubernetes cluster** with Cluster Admin access. - This tutorial can be completed with **a local Kubernetes cluster** on your machine and does not require a publicly accessible cluster, only [egress traffic](https://www.webopedia.com/definitions/egress-traffic/) (i.e., internet access). Consider using [Docker Desktop](https://duckduckgo.com/?q=docker+desktop+install) and [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation). - Admin access is required to create namespaces and cluster roles. - a [GitHub](https://github.com/) Account - you will use this to: - host **public** repositories for the control plane, demo application, and deployment configuration. - use [GitHub Codespaces](https://docs.github.com/en/codespaces/overview) to run Terraform for repository setup. - run GitHub Actions. (The repositories are public, so there is no cost.) - create an Argo CD instance on the [Akuity Platform](https://akuity.io/akuity-platform/). - the Kubernetes command-line tool, [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl). - a local IDE with access set up to your GitHub. :::tip Throughout this tutorial, all changes to repositories can be done from your **browser** by changing `github.com` to `github.dev` in the URL for the repository. See [the GitHub docs](https://docs.github.com/en/codespaces/the-githubdev-web-based-editor) for more details. ::: - a browser with internet access. This tutorial shows placeholder text between less-than and greater-than symbols (i.e., `<...>`), indicating that you must substitute it with the value relevant to your scenario. - `` - Your GitHub username. ## 2. Repositories The tutorial will use the following repositories: - The **`control-plane`** [repository](https://github.com/akuity-adv-gitops-workshop/control-plane-template) defines the desired state of the Kubernetes platform and enables self-service onboarding for teams. It contains the following directories: * `argocd` - configuration for Argo CD (e.g., `Application`s, `AppProject`s) * `charts` - local and [Umbrella](https://helm.sh/docs/howto/charts_tips_and_tricks/#complex-charts-with-many-dependencies) Helm Charts. * `clusters` - cluster-specific configurations (e.g., `ClusterSecretStore`). * `teams` - a folder for each team. - The **`demo-app`** [repository](https://github.com/akuity-adv-gitops-workshop/demo-app-template) contains the source code for a simple Golang application packaged into a container image used to demonstrate Argo CD driven GitOps processes and CI. - The **`demo-app-deploy`** [repository](https://github.com/akuity-adv-gitops-workshop/demo-app-deploy-template) uses [Kustomize](https://kustomize.io) to define the manifests to deploy the `demo-app` and contains the following directories: * `base/` - the application manifests agnostic to any environment. * `deployment.yaml` - defines the `Deployment`. * `service.yaml` - defines the `Service`. * `env/` - the overlays specific to environments. * `dev/` * `stage/` * `prod/` ### 2.1. Automated Repository Setup You will run Terraform in a [GitHub Codespace](https://docs.github.com/en/codespaces/overview) to setup the repositories and add a token to the GitHub Actions secrets of them. 1. Open the `automated-repo-setup` repo in GitHub Codespaces. - Navigate to [akuity-adv-gitops-workshop/automated-repo-setup](https://github.com/akuity-adv-gitops-workshop/automated-repo-setup/). - Click Code. - Click Create codespace on main 1. Generate a GitHub Personal Access Token (PAT). - Navigate to [https://github.com/settings/tokens/new](https://github.com/settings/tokens/new). - Or from the UI: - https://github.com/settings/profile - `Developer settings` at the bottom of the left hand menu - `Personal access tokens` -> `Tokens (classic)` - `Generate new token` -> `Generate new token (classic)` - Set Note to `adv-gitops-workshop`. - Set the Expiration to `7 days`. - Under "Select scopes", select: - `repo` - `write:packages` - `user:email` - `delete_repo` - **optional**, include if you want to use Terraform to clean up the repos after the workshop. - Click Generate token at the bottom of the page. - Copy the generated PAT. 1. Use Terraform to create the repositories. - Run `terraform apply` in the terminal of the Codespace. - When prompted for `var.github_token`, paste the PAT. - Review the plan, type `yes` then hit `return`/`enter` apply it. - This will result in the creation of three GitHub repositories under your account. :::info Bonus Question (1) What is the purpose of the `github_release.setup-complete` resource? ::: At this point, the Codespace can be stopped. 1. Hit cmd/ctrl + shift + p. 2. Enter `>codespaces: Stop Current Codespace`. 3. Hit return/enter. ### 2.2. Building Images To deploy an application using Argo CD, you need a container image. It would be boring if you deployed a pre-built image, so you will build one specific to you! You are going to leverage GitHub Actions to build an image and push it to the [GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry) (GHCR). The workflow is already defined in the repository and was triggered by the `demo-app` repository creation. 1. View the image created in the GitHub Packages page. - Navigate to `https://github.com//demo-app/pkgs/container/demo-app` The `demo-app` image is avaiable at `ghcr.io//demo-app` with the `latest` and the commit ID (SHA) tags. If the GitHub Actions workflow fails to push the `demo-app` image to the repo with the response `403`, either the token is missing the `write:packages` scope or the package already exists for the user and the repository and not added to it. ## 3. Argo CD Setup The control plane setup assumes that you have already prepared a Kubernetes cluster with internet access. ### 3.1. Creating an Argo CD Instance The tutorial demonstrates deploying resources to clusters connected to Argo CD. You will create an Argo CD instance using the Akuity Platform to simplify the installation and connecting clusters. :::tip [Sign up](https://hubs.li/Q02l2Wxt0) for a free 14-day trial of the Akuity Platform! ::: 1. Log into [the Akuity Platform](https://hubs.li/Q02l2Wxt0) with your GitHub account. - If you don't already have an organization (i.e., it's your first time logging in), create one naming it using your GitHub username. 2. [Create an Argo CD instance](03-argocd/01-getting-started/10-create-argo-cd-instance.mdx#create-an-argo-cd-instance-1) on the Akuity Platform with the name `adv-gitops` (or any permitted string). 3. Enable [Declarative Management](/03-argocd/02-managing-instances/30-settings/10-features/30-declarative-management.md#enabling-declarative-management) for the Argo CD instance. :::info Declarative Management enables using the Akuity Platform with [the App of Apps pattern](https://youtu.be/2pvGL0zqf9o) and `ApplicationSet`s by exposing the `in-cluster` destination. Using the `in-cluster` destination means an Application can create other Applications in the cluster hosting Argo CD. ::: 4. Connect your Kubernetes cluster by [creating an agent](03-argocd/01-getting-started/20-connect-kubernetes-cluster.mdx) named `workshop`. :::caution Using the name `workshop` is **crucial** because the manifests provided for the tutorial assume this is the `destination.name` available for `Application`s in Argo CD. ::: 5. [Enable the `admin` user](03-argocd/01-getting-started/30-enable-admin-user.mdx), generate the password. 6. [Access your Argo CD instance](03-argocd/01-getting-started/40-access-argo-cd-instance.mdx). ## 4. Cluster Bootstrapping ### 4.1. Automating `Application` Creation with `ApplicationSet`s Each cluster will get two addons (`kyverno` and `external-secrets`), the cluster-specific configurations, and `Namespace`s for the teams. Each requires an `Application` in Argo CD to install them into each cluster. Manually creating `Application`s is error-prone and tedious. Scripting config management tools can automate the process, but there is a better way. `ApplicationSet`s template `Application`s and populate them using [generators](https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Generators/). These are the `ApplicationSet`s in the `control-plane` repo: - [`argocd/clusters-appset.yaml`](https://github.com/akuity-adv-gitops-workshop/control-plane-template/blob/main/argocd/clusters-appset.yaml) will generate an `Application` for each cluster registered to Argo CD (excluding the `in-cluster`) and point it to the `clusters/{{name}}` folder in the `control-plane` repo. - [`argocd/addons-appset.yaml`](https://github.com/akuity-adv-gitops-workshop/control-plane-template/blob/main/argocd/addons-appset.yaml) will generate an `Application` for each combination of cluster registered to Argo CD (excluding the `in-cluster`) and Helm Chart folder in the `list` generator. ```yaml # generators - list: elements: # The value in the pairs below are the folder name from `charts/`. - addonChart: external-secrets - addonChart: kyverno - clusters: selector: matchExpressions: - {key: 'akuity.io/argo-cd-cluster-name', operator: NotIn, values: [in-cluster]} ``` The `addons-values.yaml` file from the `cluster/` folder is passed to each Helm Chart. Using Umbrella charts (setting sub-charts as dependencies in the local chart), the same values file can be passed to each chart, without fear of conflicts. ```yaml # cluster/{{name}}/addons-values.yaml external-secrets: {} kyverno: {} # values file from cluster folder source: helm: valueFiles: - '../../clusters/{{name}}/addons-values.yaml' ``` - [`argocd/teams-appset.yaml`](https://github.com/akuity-adv-gitops-workshop/control-plane-template/blob/main/argocd/teams-appset.yaml) will generate an `Application` for each folder in `teams/`. The resulting `Application` will use the `team` Helm Chart (in the `charts/ folder`) with the `values.yaml` from the team's folder. ```yaml # File structure of the `teams` folder. teams/ / values.yaml # ApplicationSet `git` generator. - git: repoURL: https://github.com//control-plane revision: HEAD directories: - path: "teams/*" # Application spec template using the values file. source: helm: releaseName: '{{path.basename}}' # The team name. valueFiles: - '../../{{path}}/values.yaml' # The team's folder. ``` - In the `team` Helm Chart, the [`repo-appset.yaml`](https://github.com/akuity-adv-gitops-workshop/control-plane-template/blob/main/charts/team/templates/repo-appset.yaml#L1) template will create an `ApplicationSet` for each item in the `repos` value. Each one will generate an `Application` for the repository name and all the folders found under `env/`. ```yaml {{- range .Values.repos }} --- apiVersion: argoproj.io/v1alpha1 kind: ApplicationSet metadata: name: '{{ $.Release.Name }}-{{ . | trimSuffix "-deploy" }}' spec: generators: - git: repoURL: 'https://github.com/{{ $.Values.githubOrg | default $.Release.Name }}/{{ . }}' revision: HEAD directories: - path: env/* template: metadata: name: '{{ $.Release.Name }}-{{ . | trimSuffix "-deploy" }}-{{`{{path.basename}}`}}' spec: project: '{{ $.Release.Name }}' source: repoURL: 'https://github.com/{{ $.Values.githubOrg | default $.Release.Name }}/{{ . }}' targetRevision: 'HEAD' path: '{{`{{path}}`}}' destination: name: '{{ $.Values.cluster }}' namespace: '{{ $.Release.Name }}-{{`{{path.basename}}`}}' syncPolicy: automated: {} {{- end }} ``` - Notice the use of ``{{`{{`` in the `path` of the template; this is to prevent Helm from interpreting the `ApplicationSet` template (`{{path}}`) syntax during templating of the chart. ### 4.2. Bootstrapping with App of Apps To enable the GitOps process, a top-level `Application` is used to manage the Argo CD configuration and propagate repository changes to the `argocd` namespace on the `in-cluster` destination (i.e., the Akuity Platform control plane). 1. Navigate to the Argo CD UI. 2. Create an Application to manage the Argo CD configuration using the `argocd-app.yaml` manifest at the root of the `control-plane` repo. - Click + NEW APP. - Click EDIT AS YAML. - Paste the contents of `argocd-app.yaml`. - Click SAVE. - Click CREATE. ![`argocd` Applcation resource tree.](argocd-app.png) After creating the `argocd` `Application`, the automated sync policy deployed the `addons`, `clusters`, `teams` `ApplicationSet`s, along with the `default` `AppProject` (assuming ownership of the existing project). The `clusters` `ApplicationSet` generated an `Application` for the `workshop` cluster, which created a couple of Kyverno `ClusterPolicy` resources and an External Secrets `SecretStore`. The `addons` `ApplicationSet` generated a Kyverno and External Secrets `Application` for the `workshop` cluster. The `addons` create the CRDs on which resources in the `cluster` `Application` depend. This setup relies on the sync retry mechanism to make the resources eventually consistent. ## 5. Self-service Teams Each team needs an `AppProject`, a `Namespace` for each environment, and `Application`s. A team can request to create these resources, but they are ultimately managed by the administrators who approve the Pull Request. The teams are provided with a Helm Chart, `charts/teams` to abstract the concepts of Namespaces, `AppProject`s, and `ApplicationSet`s. Instead, they must create a new folder under `teams/` and add the example `values.yaml` from `teams/USERNAME`. ### 5.1. Creating a Team Environment You will create a team for the tutorial using your GitHub username. 1. Open the `control-plane` repository. 2. Copy the `teams/EXAMPLE` folder and create a new folder with your GitHub username, converting to lowercase if required. (i.e., `teams/`) 3. Commit the changes to the `main` branch. Once the `teams` `ApplicationSet` has detected the change in Git, it will create an `Application` for the `Namespace`s on the cluster, the `AppProject` for the team, and an `ApplicationSet` for each repo in the `values.yaml`. On the Applications page of Argo CD, select the team's project on the filter to experience what they would see. The `demo-app` is deployed using the `latest` tag to each namespace. Check out the `Deployment` logs to confirm that your `` is being printed. :::info Bonus Question (2) Why is a separate Application used to create the `Namespace` resources instead of using the `CreateNamespace` sync option? ::: ## 6. Rendered Manifests Using config management tools, like [Kustomize](https://kustomize.io), makes it much easier to maintain the environment-specific configuration. However, it also makes it much more challenging to determine what exactly changed in the resulting manifests. This is a critical requirement for production environments. Luckily there is a solution for this, the Rendered Manifests pattern! The idea is to create a branch with plain YAML manifests generated by the config management tool (i.e., Kustomize). The process of maintaining rendered manifests branches, of course, should be automated. A Continuous Integration system, like GitHub Actions, is a perfect tool for this task. ### 6.1. Adding Render Manifests to the `demo-app-deploy` Repo The `demo-app-deploy` repo contains the application's manifests, so you'll add a workflow to generate the rendered manifests. 1. Navigate to your `demo-app-deploy` repo. 2. Open `.github/workflows/rendered-manifests.yaml`: - Uncomment the `render-manifests` job. - Delete the `placeholder` job. - Commit and push the changes. - Once the workflow is created, it will create a branch for each environment and push the rendered manifests to the branch. 3. Navigate to your `control-plane` repository to update the `team` Helm Chart (`charts/team`) to use the rendered manifests from the branches. - Open the file `charts/team/templates/repo-appset.yaml`. - Update the `spec.template.spec.source.targetRevision` to `{{ "{{" }}path{{ "}}" }}` - Update the `spec.template.spec.source.path` to `./` ```diff # charts/team/templates/repo-appset.yaml apiVersion: argoproj.io/v1alpha1 kind: ApplicationSet metadata: name: '{{ $.Release.Name }}-{{ . | trimSuffix "-deploy" }}' spec: template: spec: source: -- targetRevision: 'HEAD' -- path: '{{ "{{" }}path{{ "}}" }}' ++ targetRevision: '{{ "{{" }}path{{ "}}" }}' ++ path: './' ``` Wait for the `ApplictionSet` to reconcile and see that nothing changes in the `Application`s since the rendered manifests are the same as what was already deployed. ## 7. Automating Image Tag Updates Updating the image tag in the `kustomization.yaml` is boring, and no one likes to make trivial tag changes manually. To make the process more efficient, you are going to automate this process with GitHub Actions! ### 7.1. Automating the `dev` Environment The `dev` environment is intended to track the trunk of the repository (i.e., the main branch), and there is minimal impact if a change breaks the application. Given this, you will automate the deployment to `dev` each time a new build is created in the `demo-app` repo. 1. Navigate to your `demo-app` repository. 2. Uncomment the `deploy-dev` job in `.github/workflows/ci.yaml` workflow file: ```yaml deploy-dev: runs-on: ubuntu-latest needs: build-image steps: - uses: imranismail/setup-kustomize@v1 - name: Update env/dev image with Kustomize run: | git config --global user.name "Deploy Bot" git config --global user.email "no-reply@akuity.io" git clone https://bot:${{ secrets.DEPLOY_PAT }}@github.com/${{ github.repository_owner }}/demo-app-deploy.git cd demo-app-deploy/env/dev kustomize edit set image ghcr.io/${{ github.repository_owner }}/demo-app:${{ github.sha }} git commit -a -m "chore(dev): deploy demo-app:${{ github.sha }}" git notes append -m "image: ghcr.io/${{ github.repository_owner }}/demo-app:${{ github.sha }}" git push origin "refs/notes/*" --force && git push --force ``` 3. Commit and push the changes, then watch the action run! ![ci-deploy-dev-action-running](ci-deploy-dev-action-running.png) When the workflow completes (successfully), check out the latest commit on your `demo-app-deploy` repo. ![demo-app-deploy-auto-dev-commit](demo-app-deploy-auto-dev-commit.png) Once changes are pushed, the CI workflow will build a new image and update the `dev` environment with the corresponding image tag. Developers no longer need to manually change deployment manifests to update the `dev` environment. ### 7.2. Automating Promotion to `stage` and `prod` Updating the manifests for the `stage` and `prod` deployments requires a more careful process, but it can also be automated. 1. Allow GitHub Actions to create and approve pull requests on the `demo-app` repo. - Navigate to: `https://github.com//demo-app-deploy/settings/actions` - Under Workflow permissions, check the box for Allow GitHub Actions to create and approve pull requests. - Click Save. 2. In your `demo-app-deploy` repo, open `.github/workflows/promote.yaml`: - Uncomment the `promote-image-change` job. - Delete the `placeholder` job. - Commit and push the changes. While the workflow is running, read on to learn more about the logic. Engineers might make arbitrary changes in the deployment repository, but you must automate only the image change. To distinguish between the image change and other changes, it uses [git notes](https://git-scm.com/docs/git-notes) to explicitly annotate the image promotion commit. The workflow checks the commit note, and if it contains the note that matches the `image: ` pattern, then propagates the image change to the staging and production environments. Remember the approval step requirement. The approval step is implemented using GitHub Pull Request. Instead of updating the production environment directly, workflow pushes the changes to the `auto-promotion-prod` branch and creates a pull request, so to approve the change approver needs to merge the pull request. 3. To demonstrate the `promotion` workflow, make a change in your `demo-app` repo. Some suggestions: - Add another exclamation mark to the output. - Change the colo**u**r of the text. - Break it somehow, promote that bug into `prod` at `17:00` on a Friday, then see how quickly you can get the fix to prod. - The real challenge is creating the bug since it fails fast (can't just be a syntax error because the build will fail.) - Use the colour `brown` as it is invalid. This fix (and the initial feature depending on the fix) will be out to prod in `~2:30`. Plus, there was no actual downtime since the pod never became healthy, and the original replicaSet stayed up. ## 8. Summary To summarize what you've built so far, you have a multi-tenant Argo CD instance. The instance is managed using a GitOps-based process where engineers can self-onboard their team by creating a pull request. Each application development team independently manages their application by maintaining a separate deployment repository. Deployment manifests are generated using Kustomize, allowing engineers to avoid duplications and efficiently introduce environment-specific changes. The simple image tag changes are fully automated using the CI pipelines. On top of this, teams leverage the "rendered manifests" pattern that turns to get Git history into a traceable audit log of every infrastructure change. Believe it or not, you've achieved more than many companies in several years. ## 9. Clean Up Complete this clean-up checklist after completing the tutorial. After doing so, you can follow the tutorial from the start again. 1. Delete the Argo CD instance on the Akuity Platform. 3. Delete the `control-plane`, `demo-app`, and `demo-app-deploy` repos. - This step can be completed by running `terraform destory` in the Codespace used during the automated repo setup. 4. Delete the `workshop` cluster. 5. Delete the `demo-app` package from your GitHub account. 6. Delete GitHub PATs generated. ## 10. Bonus Question Answers 1. The repositories have a GitHub Actions workflow (`update-placeholders.yaml` ) to update placeholder text in the files from the repository templates. The challenge is that the `DEPLOY_PAT`, created in the same Terraform apply, needs to exist before the workflow can be run. The `github_release.setup-complete` resource creates a tag named `setup-complete` on the repositories to trigger the workflow and it `depends_on` the `github_actions_secret.deploy-pat` resource, which ensures that the workflow is run after the GitHub Secret is added. 2. The `AppProject` for the team only permits creating resources in the specified cluster and namespaces matching the pattern `-*`. This means that `Namespace` resources can't be created by `Application`s in the team's project. Instead a seperate `Application` is created in the `default` project, which does permit `Namespace` resources. --- ## Migrating from Open-Source Argo CD The Akuity Platform automates the deployment of the upstream version of Argo CD, but packages it in a [unique hybrid architecture](../../01-overview/10-architecture.md) that significantly improves performance and scalability. However, the API, CLI, UI, and CRDs will be no different than open-source Argo CD. The main considerations during a migration to an Argo CD instance on the Akuity Platform will come down to implementation details. :::tip [Sign up](https://hubs.li/Q02l2W-b0) for a free 14-day trial of the Akuity Platform! ::: ## Considerations ### Applications Targeting the `in-cluster` Destination When running the open-source Argo CD, it’s common to deploy resources into the same cluster that Argo CD is running in. This is known as the `in-cluster` destination (or the server URL `https://kubernetes.default.svc`). On the Akuity Platform, `in-cluster` refers to the control plane hosting your Argo CD instance. You can only deploy `Application`, `ApplicationSet`, and `AppProject` resources to this destination (see the [Declarative Management](../../03-argocd/02-managing-instances/30-settings/10-features/30-declarative-management.md)). When migrating to the Akuity Platform, any cluster that Argo CD will manage resources in will be connected by deploying the [Akuity Agent](../../03-argocd/02-managing-instances/20-clusters/index.md) into it. This means `Application`s that were targeting the `in-cluster` destination to deploy resources other than `Application`, `ApplicationSet`, and `AppProject`, will now need to target a named cluster. For example, this `Application` was targeting the `in-cluster` destination: ```yaml apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: guestbook spec: project: default source: repoURL: 'https://github.com/argoproj/argocd-example-apps' path: guestbook targetRevision: HEAD destination: namespace: default name: in-cluster # <-- syncPolicy: automated: {} ``` While migrating to the Akuity Platform, the cluster was connected using the agent and was given the name `my-cluster`. So the `destination.name` of the `Application` will need to be changed from `in-cluster` to `my-cluster`. ```diff destination: namespace: default -- name: in-cluster ++ name: my-cluster ``` :::tip It’s recommended to use the `destination.name` over the `destination.server` as it provides greater flexibility (since a server URL using an IP address or generated FQDN can change if a cluster is recreated, but the name will remain the same) and improves the readability of the Application destination (the name will match that of the cluster name used when provisioning the Akuity Agent). ::: Application’s used for [the App of Apps pattern](https://www.youtube.com/watch?v=2pvGL0zqf9o) (i.e. that deploy other `Application` resources) can continue to target the `in-cluster` destination. However, any child `Application`s that target the `in-cluster` destination will need to be updated to target the connected cluster by name (or server URL). ### Resource Tracking Method The Akuity Platform takes advantage of the `annotation` [resource tracking](https://argo-cd.readthedocs.io/en/stable/user-guide/resource_tracking/) method. On first sync of an `Application` with existing resources, Argo CD will add the `annotation` and if the original Argo CD instance used the default `label` or `annotation+label` methods, it will remove the label. On the original instance, if it still has the `Application` and is monitoring those resources, the `Application` will show as out-of-sync with a diff for the annotation and label. ![Resource Tracking Diff](resource-tracking-method-diff.png) To avoid this, update the original instance to use [the `annotation` resource tracking method](https://argo-cd.readthedocs.io/en/stable/user-guide/resource_tracking/#choosing-a-tracking-method) prior to switching to the Akuity Platform. ### Non-cascading Deletion of `Application`s When removing `Application`s from the original Argo CD instance, it's important to use the [non-cascading](https://argo-cd.readthedocs.io/en/stable/user-guide/app_deletion/) propagation policy to ensure the `Application` is deleted without pruning the resources managed by it. ## Step-by-Step Guide to an Active-Active Migration This guide will cover how to do an Active-Active migration from an open-source Argo CD installation to an instance on the Akuity Platform. The goal is to have both instances in the cluster as `Application`s are moved over incrementally. Then the original Argo CD instance is torn down without any impact to the running workloads. Your specific implementation of Argo CD may vary from the assumptions of the guide. It's highly recommended to start with the lowest-impact `Application`s to ensure that there are no unexpected side effects. To start off, let's assume you have Argo CD running in the `argocd` namespace of the managed cluster. ``` % k get deploy -n argocd NAME READY UP-TO-DATE AVAILABLE AGE argocd-applicationset-controller 1/1 1 1 14d argocd-dex-server 1/1 1 1 14d argocd-notifications-controller 1/1 1 1 14d argocd-redis 1/1 1 1 14d argocd-repo-server 1/1 1 1 14d argocd-server 1/1 1 1 14d ``` After [creating an Argo CD instance](../../03-argocd/01-getting-started/10-create-argo-cd-instance.mdx) on the Akuity Platform of **the same version** as the original installation, install the Akuity Agent into the `akuity` namespace of the same cluster. :::warning The Akuity Agent is intentionally installed in a separate namespace (`akuity`) from the Argo CD installation (`argocd`) because they both create resources with the same names. For example, both will create an `argocd-repo-server` `Deployment`. ::: ``` % k get deploy -n akuity NAME READY UP-TO-DATE AVAILABLE AGE akuity-agent 2/2 2 2 82s argocd-application-controller 1/1 1 1 82s argocd-applicationset-controller 0/0 0 0 82s argocd-image-updater 0/0 0 0 82s argocd-notifications-controller 1/1 1 1 82s argocd-redis 1/1 1 1 81s argocd-repo-server 2/2 2 2 81s ``` Now, on the Akuity Platform Argo CD instance, create the same `Application` as on the original instance. If the original destination was `in-cluster`, make sure to update the `destination.name` (or `destination.server`) to reflect the new cluster. At this point, both instances will be monitoring and managing the resources for the Application. On the original Argo CD instance, delete the Application using the [non-cascading propagation policy](https://argo-cd.readthedocs.io/en/stable/user-guide/app_deletion/). At this point, the Akuity Platform Argo CD instance will manage the `Application` and it’s resources. --- ## Cluster Add-ons with ApplicationSets - [1. Overview](#1-overview) - [1.1. Prerequisites](#11-prerequisites) - [2. Creating the Workshop Environment](#2-creating-the-workshop-environment) - [2.1. Kubernetes Clusters using `devcontainer`](#21-kubernetes-clusters-using-devcontainer) - [2.2. Akuity Platform Sign Up](#22-akuity-platform-sign-up) - [2.3. Create your Argo CD Instance](#23-create-your-argo-cd-instance) - [2.3.1. Configure Your Instance](#231-configure-your-instance) - [2.3.2. Deploy an Agent to the Cluster](#232-deploy-an-agent-to-the-cluster) - [2.3.3. Bootstrapping Argo CD](#233-bootstrapping-argo-cd) - [3. Enabling Cluster Add-ons](#3-enabling-cluster-add-ons) - [3.1. `addons` `ApplicationSet`s](#31-addons-applicationsets) - [3.2. Enable the `cert-manager` Add-on for `dev`](#32-enable-the-cert-manager-add-on-for-dev) - [4. Deploying Applications](#4-deploying-applications) - [4.1. `cluster-apps` `ApplicationSet`](#41-cluster-apps-applicationset) - [4.2. Mark the Cluster as Ready](#42-mark-the-cluster-as-ready) ## 1. Overview Managing clusters at scale requires standardization and automation. Tasks that looked trivial with a handful of clusters become a burden when managing tens or even hundreds of them.
How did we get here? Read the backstory here. *Backstory by from the perspective of a cluster administrator named Nick.* While scrolling through Slack one morning, Nick got a ping that one of the product teams wanted to do performance testing on their application because of a new feature launch that ties together many different services. They are worried about how the influx of traffic might effect the environment. Given this fear, Nick decided to provision an environment dedicated to performance testing, base the `stage` environment. Right now, they are using a cluster for each environment (`dev`, `stage`, and `prod`) with folders for each one that contains the Argo CD Applications for the “add-ons” (a standard set of Kubernetes resources used by applications, expected to be on every cluster). ![diagram of cluster folders](./folder-per-cluster-diagram.png) Adding this new environment with a new cluster requires lots of copying and pasting of Argo CD `Applications` from an existing cluster configuration to a folder for the new one, and changing any details specific to the cluster (e.g. cluster name). While not a huge burden at this scale, it’s easy to forget to change something. ![diagram of copying Applications between cluster folders](./folder-per-cluster-diagram-plus-perf.png) Nick updated the Terraform configuration to set up the new `perf` environment and create the cluster. Nick added the cluster to the central Argo CD instance and created the App-of-Apps to deploy the `Applications` from the cluster’s folder in their GitOps repo. Then, Nick confirmed that all of the `Applications` were synced and healthy. ![diagram of terraform creating a cluster and argo cd pull from git to the cluster](./tf-k8s-cd-git.png) After handing over the reins to the product team, Nick got a ping on Slack from a developer who deployed their application to the `perf` environment, but it’s not working the way it did in `stage`. After some investigation, Nick found that, in the transition to the new cluster, the `Application` for `cert-manager` pointed to the values file of the `stage` cluster. The values file contained the wrong subdomain, leading to the DNS challenge failing when the dev’s application requested a new cert—a minor oversight when copying over the Argo CD `Applications` for the new cluster’s add-ons. ![diagram of mistake copying Applications](./the-mistake.png) Nick thinks to himself, there must be a better way! A life without toil. 💡
In this tutorial presented by [Akuity](https://akuity.io), attendees will learn how to leverage `ApplicationSets`, a powerful Argo CD feature, to streamline the deployment of a standard set of "add-ons" (like Sealed Secrets, cert-manager, and Kyverno) to each cluster. We will address the dynamic nature of clusters by demonstrating how they can "opt-in" to specific tooling and configurations, allowing for flexibility without sacrificing standardization. Manually creating `Application`s is error-prone and tedious. Especially if the `Applications` are nearly identical aside from a few values that can be determined automatically. `ApplicationSet`s template `Application`s and populate them using [generators](https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Generators/). ![diagram of an ApplicationSet creating](./applicationset-applications.png) In the `control-plane` repo, the `bootstrap` folder contains two `ApplicationSets`, one for the cluster add-ons (`cluster-addons-appset.yaml`) and one for the cluster apps (`cluster-apps-appset`). The distinction between "add-ons" and "apps" is delineation between cluster admin and developer. The cluster admin is primarily responsible for the "add-ons" as they are central to cluster and used by many other teams. The developers are responsible for their apps. ![diagram with two ApplicationSets with one for add-ons and one for apps with dev/admin split](appsets-dev-admins.png) ### 1.1. Prerequisites The tutorial assumes you have experience working with Kubernetes, GitOps, and Argo CD. Given such, some underlying concepts won't be explained during this tutorial. The tutorial requires that you have the following: - a [GitHub](https://github.com/) Account. - the ability to run a [`devcontainer`](https://containers.dev/). Either: - using [GitHub Codespaces](https://github.com/features/codespaces), - locally with the [VS Code Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) and Docker, - or with [DevPod](https://devpod.sh/docs/what-is-devpod). - a browser with internet access. ## 2. Creating the Workshop Environment ### 2.1. Kubernetes Clusters using `devcontainer` To demonstrate multi-cluster management, you will create an environment for this workshop using a [`devcontainer`](https://containers.dev/). The `devcontainer` will be built based on the specification in the [`devcontainer.json`](https://github.com/akuity-cluster-addons-workshop/control-plane/blob/main/.devcontainer/devcontainer.json) in the workshop repo. Then, it will start up two [`minikube`](https://minikube.sigs.k8s.io/docs/) clusters named `dev` and `prod`. **GitHub Codespace** The easiest way to get started is with GitHub Codespaces (especially if you are on conference wifi). [![Open workshop in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/akuity-cluster-addons-workshop/control-plane?quickstart=1) **VSCode (local)** Alternatively, you can run the workshop using the VS Code Dev Containers extension and Docker on your machine. - Clone the akuity-cluster-addons-workshop/control-plane repo to your machine. - Open the `control-plane` repository in VSCode. - Ensure you have installed the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension. - Run the `Dev Containers: Open Folder in Container...` command in VSCode and select the local folder. - `Shift + Command/Ctrl + P` + `Dev Containers: Open Folder in Container...` ### 2.2. Akuity Platform Sign Up This scenario demonstrates deploying applications to a cluster external to Argo CD. Similar to how the GitHub repo is hosting the Helm charts, which describe **what** resources to deploy into Kubernetes, the Akuity Platform will host the Application manifests, which represent **how** to deploy the resources into the cluster. Along with Argo CD, which will implement the changes on the cluster. :::tip [Sign up](https://training.akuity.cloud/) for a free 30-day trial of the Akuity Platform! ::: 1. Create an account on the [Akuity Platform](https://training.akuity.cloud/). 2. To log in with GitHub SSO, click "Continue with GitHub". :::note You can also use Google SSO or an email and password combo. ::: 3. Click Authorize akuityio. 4. Click the create or join link. 5. Click + New organization in the upper right hand corner of the dashboard. 6. Name your organization following the rules listed below the Organization Name field. ### 2.3. Create your Argo CD Instance You can create your Argo CD instance using the Akuity Platform **Dashboard or CLI** by choosing between the tabs below. **Bash Script** 1. Log into the `akuity` CLI. ``` akuity login ``` - Open the link displayed: [https://akuity-training.us.auth0.com/activate](https://akuity-training.us.auth0.com/activate) - Enter the code displayed. 1. Run the Bash script. ``` ./.devcontainer/setup-akuity-platform.sh ``` **CLI** 1. Check your `akuity` CLI version. ``` akuity version ``` 2. Log into the `akuity` CLI. ``` akuity login ``` - Open the link displayed: [https://akuity-training.us.auth0.com/activate](https://akuity-training.us.auth0.com/activate) - Enter the code displayed. 3. Set your organization name in the `akuity` config in one command using some bash-fu: ``` akuity config set --organization-id=$(akuity org list | awk 'NR==2 {print $1}') ``` 4. Create the Argo CD instance on the Akuity Platform ``` akuity argocd apply -f akuity-platform/ ``` 5. Apply the agent install manifests to the clusters. ``` kubectx k3d-dev && \ akuity argocd cluster get-agent-manifests \ --instance-name=cluster-addons dev | kubectl apply -f - ``` ``` kubectx k3d-prod && \ akuity argocd cluster get-agent-manifests \ --instance-name=cluster-addons prod | kubectl apply -f - ``` 6. From the Akuity Platform Dashboard, in the top, next to the Argo CD instance name and status, click the instance URL (e.g., `.cd.akuity.cloud`) to open the Argo CD login page in a new tab. 7. Enter the username `admin` and the password `akuity-argocd`. 8. Log into the `argocd` CLI ``` argocd login \ "$(akuity argocd instance get cluster-addons -o json | jq -r '.id').cd.training.akuity.cloud" \ --username admin \ --password akuity-argocd \ --grpc-web ``` **Dashboard** 1. Navigate to Argo CD. 2. Click + Create in the upper right hand corner of the dashboard. 3. Name your instance following the rules listed below the Instance Name field. 4. (Optionally) Choose the Argo CD version you want to use. 5. Click + Create. At this point, your Argo CD instance will begin initializing. The start-up typically takes under 2 minutes. #### 2.3.1. Configure Your Instance While the instance is initializing, you can prepare it for the rest of the lab. 1. In the dashboard for the Argo CD instance, click Settings. 2. On the inner sidebar, under "Security & Access", click System Accounts. 3. Enable the "Admin Account" by clicking the toggle and clicking Confirm on the prompt. 4. Then, for the `admin` user, click Set Password. 5. Enter the password `akuity-argocd`, then click Submit. 6. In the top, next to the Argo CD instance name and status, click the instance URL (e.g., `.cd.akuity.cloud`) to open the Argo CD login page in a new tab. 7. Enter the username `admin` and the password `akuity-argocd`. 8. Log into the `argocd` CLI ``` argocd login \ ".cd.training.akuity.cloud" \ --username admin \ --password akuity-argocd \ --grpc-web ``` #### 2.3.2. Deploy an Agent to the Cluster You must connect the cluster to Argo CD to deploy the application resources. The Akuity Platform uses an agent-based architecture for connecting external clusters. So, you will provision an agent and deploy it to the cluster. 1. Back on the Akuity Platform, in the top left of the dashboard for the Argo CD instance, click Clusters. 2. In the top right, click Connect a cluster. 3. Enter the `dev` name as the "Cluster Name". 4. In the bottom right, click Connect Cluster. 5. To get the agent install command, click Copy to Clipboard. Then, in the bottom right, Done. 6. Open your terminal and set the cluster context to `dev` by running: ``` cluster-dev ``` 7. Paste and run the command against the cluster. The command will create the `akuity` namespace and deploy the resources for the Akuity Agent. 8. Check the pods in the `akuity` namespace. Wait for the `Running` status on all pods (approx. 1 minute). ``` % kubectl get pods -n akuity NAME READY STATUS RESTARTS AGE akuity-agent-- 1/1 Running 0 65s akuity-agent-- 1/1 Running 0 65s argocd-application-controller-- 2/2 Running 0 65s argocd-notifications-controller-- 1/1 Running 0 65s argocd-redis-- 1/1 Running 0 65s argocd-repo-server-- 1/1 Running 0 64s argocd-repo-server-- 1/1 Running 0 64s ``` Re-run the `kubectl get pods -n akuity` command to check for updates on the pod statuses. 9. Back on the Clusters dashboard, confirm that the cluster shows a green heart before the name, indicating a healthy status. 10. Repeat these steps for the `prod` cluster. #### 2.3.3. Bootstrapping Argo CD To deploy the `ApplicationSets` that will automate the creation of `Applications` for your clusters, you will manually create an initial `bootstrap` `Application`. 1. Navigate to the UI of your Argo CD instance. 2. Create an `Application` to manage the Argo CD configuration using [the `bootstrap-app.yaml` manifest](https://github.com/akuity-cluster-addons-workshop/control-plane/blob/main/akuity-platform/bootstrap-app.yaml) in the workshop `control-plane` repo. - Click + NEW APP. - Click EDIT AS YAML. - Paste the contents of `bootstrap-app.yaml`. - Click SAVE. - Click CREATE. You now have a fully-managed Argo CD instance 🎉 After the `bootstrap` `Application` automatically syncs, it will create two `ApplicationSets`: `cluster-addons` and `cluster-apps`. Notice that they do **not** create any `Applications`. Each cluster can *opt-in* to add-ons, meaning that nothing is deployed unless the cluster indicates that it should be. ## 3. Enabling Cluster Add-ons ### 3.1. `addons` `ApplicationSet`s For each add-on there is a corresponding `ApplicationSet`. ```yaml bootstrap: - appset-addon-cert-manager.yaml - appset-addon-external-secrets.yaml - appset-addon-kyverno.yaml ``` Each `ApplicationSet` will use the `cluster` generator to create an `Application` per cluster registered to Argo CD, but only if two conditions are met: 1. The cluster name (from the `akuity.io/argo-cd-cluster-name` label) is not `in-cluster`. This condition prevents Argo CD from attempting to deploy add-ons to the cluster it is running in. 2. The cluster contains a label in the format `enable_`. This ensures that cluster's opt-in to add-ons, rather than deploying add-ons to every cluster by default. ```yaml generators: - clusters: selector: matchExpressions: # Don't deploy addons to cluster running Argo CD (i.e. the Akuity Platform). - {key: 'akuity.io/argo-cd-cluster-name', operator: NotIn, values: [in-cluster]} # Check annotation to see if addon is enabled. - key: enable_cert_manager operator: In values: ['true'] ``` The results from the generator look like: ```yaml - name: prod nameNormalized: prod server: https://cluster-prod:8001 metadata: labels: key: value annotations: key: value ``` The labels and annotations are sourced from the cluster configuration, which on the Akuity Platform is defined in the `Cluster` resource (or from the Dashboard). ```yaml apiVersion: argocd.akuity.io/v1alpha1 kind: Cluster metadata: name: dev labels: environment: "dev" enable_cert_manager: true ``` In addition to the selectors on the `clusters` generator, it includes `values` which are added to each result for use in the `Application` template. The `addonChartVersion` value is used to specify the version of the Helm chart to deploy. ```yaml generators: - clusters: values: # Default chart version addonChartVersion: v1.13.1 ``` These values are used in combination with a top-level `merge` generator to enable specifying the Helm chart version based on the environment (arbitrary groupings of clusters). ```yaml generators: - merge: mergeKeys: [server] generators: # ... (main cluster generator) - clusters: selector: matchLabels: environment: dev values: addonChartVersion: v1.14.5 ``` The `merge` generator will combine the results from the two generators based on the `server` key. The `values` on the main `clusters` generator become the default. The `addons` are sourced directly from the Helm chart repositories, along with values files from a Git repository. Traditionally to accomplish this combination would require using a Helm umbrella chart or specifying the values in the `Application` manifest. However, here you will take advantage of the multiple sources feature added in Argo CD version `2.6`. ```yaml sources: # Helm chart source. - repoURL: 'https://charts.jetstack.io' chart: 'cert-manager' targetRevision: '{{.values.addonChartVersion}}' helm: releaseName: 'cert-manager' ignoreMissingValueFiles: true valueFiles: - '$values/clusters/{{.name}}/addons/cert-manager.yaml' # Helm valueFiles source. - repoURL: 'https://github.com/akuity-cluster-addons-workshop/control-plane' targetRevision: 'HEAD' ref: values ``` The first source is for the Helm chart repository, which uses the `addonChartVersion` from the generator as the `targetRevision` for the Helm chart. Then, each cluster can specify overrides to the defaults values with a file with the same name as the add-on in the `clusters//addons/` folder (e.g. for the `prod` cluster and `cert-manager` add-on, the values file would be `clusters/prod/addons/cert-manager.yaml`). ``` clusters/ dev/ addons/ cert-manager.yaml ``` The second source will fetch the cluster-specific values file from the GitOps repository for use with the first source. The `ref` value in the second source sets the name (`values`) to target files in it from other sources. The first source uses this in the `helm.valueFiles` to tell Argo CD to reference the second source as the root and then includes the path to the values file in that source. ```yaml ref: values #... helm: valueFiles: - '$values/clusters/{{.name}}/addons/cert-manager.yaml' ``` ### 3.2. Enable the `cert-manager` Add-on for `dev` You'll start by deploying the `cert-manager` add-on for the `dev` cluster by adding the `enable_cert_manager: true` label to the cluster configuration. **CLI** Run the following command: ``` akuity argocd cluster update \ --instance-name=cluster-addons dev \ --label enable_cert_manager=true ``` **Dashboard** 1. Navigate to the Clusters dashboard for your Argo CD instance on the Akuity Platform. 2. Click the settings cog on the right side of the `dev` cluster. 3. Under the "Labels" section click Add Label. 4. Set the key to `enable_cert_manager` and the value to `true` 5. Click Update Cluster. Return to Argo CD UI to see the `cluster-addons` `ApplicationSet` immediately create the `addons-dev-cert-manager` `Application`, which will deploy `cert-manager` to the `dev` cluster. It's using the Helm Umbrella chart from the `charts/add-ons/cert-manager` folder of the `control-plane` repo. ## 4. Deploying Applications ### 4.1. `cluster-apps` `ApplicationSet` The `apps` are unique to each cluster, so they are located in `cluster/` `Application` which points to the `cluster//apps` folder (using the `name` attribute supplied by the `cluster` generator). ```yaml metadata: name: 'apps-{{name}}' ... source: repoURL: https://github.com/akuity-cluster-addons-workshop/control-plane targetRevision: HEAD path: 'clusters/{{name}}/apps' ``` The `Application` is configured to take any plain Kubernetes manifest in the folder and deploy it to the Argo CD control-plane (i.e. the `in-cluster` destination in the `argocd` namespace). Therefore, it is expected to contain Argo CD manifests (e.g. `Application`, `ApplicationSet`, and `AppProject`). ```yaml source: ... directory: recurse: true destination: name: 'in-cluster' namespace: 'argocd' ``` ### 4.2. Mark the Cluster as Ready Now that the add-ons have been deployed to the cluster, you'll add the `ready: true` label to the cluster configuration mark the cluster as ready for Applications. **CLI** Run the following command: ``` akuity argocd cluster update \ --instance-name=cluster-addons dev \ --label ready=true ``` **Dashboard** 1. Navigate to the Clusters dashboard for your Argo CD instance on the Akuity Platform. 2. Click the settings cog on the right side of the `dev` cluster. 3. Under the "Labels" section click Add Label. 4. Set the key to `ready` and the value to `true` 5. Click Update Cluster. Return to Argo CD UI to see the `cluster-apps` `ApplicationSet` immediately create the `guestbook-dev` `Application` from the `clusters/dev/apps/` folder in the `control-plane` repo. --- ## Declarative Management of the Akuity Platform On the [Akuity Platform](https://akuity.io/akuity-platform/), Argo CD instances and their configuration can be defined declaratively using Kubernetes and Kubernetes-like manifests, and managed using the `akuity` CLI (or API). In this tutorial, you will create an Argo CD instance on the Akuity Platform based on manifests stored in a Git repo. ![ArgoCD Manifest in GitHub](./argocd-manifest.png) :::info This tutorial is accompanied by a GitHub repository: [akuity/declarative-example](https://github.com/akuity/declarative-example) ::: ## Create Your Environment From the GitHub repository, you can create an environment using a [`devcontainer`](https://containers.dev/) (based on the [`devcontainer.json`](https://github.com/akuity/declarative-example/blob/main/.devcontainer/devcontainer.json) in the repo). This environment will come preloaded with: - A Kubernetes cluster using [`kind`](https://kind.sigs.k8s.io/). - The [`akuity`](/akuity-portal/reference/cli/akuity), [`argocd`](https://argo-cd.readthedocs.io/en/stable/user-guide/commands/argocd/) and [`kubectl`](https://kubernetes.io/docs/akuity-portal/reference/kubectl/kubectl/) CLIs. **GitHub Codespace** The easiest way to get started is with GitHub Codespaces. Click the button below to launch an environment in GitHub Codespaces. [![Launch environment in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/akuity/declarative-example?quickstart=1) **VSCode (local)** Alternatively, you can run the environment using the VS Code Dev Containers extension and Docker on your machine. - Clone the akuity/declarative-example repo to your machine. - Open the `declarative-example` repository in VSCode. - Ensure you have installed the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension. - Run the `Dev Containers: Open Folder in Container...` command in VSCode and select the local folder. - `Shift + Command/Ctrl + P` + `Dev Containers: Open Folder in Container...` **Without devcontainer (manual)** The bare minimum requirements to follow this tutorial are: - a [Kubernetes](https://kubernetes.io/) cluster with internet access (egress traffic, no port-forwarding is required). - a GitHub account. To follow along: 1. Create a Kubernetes cluster that you want to deploy resources to with Argo CD and set that to your current `kubectl` context. You can manage the Akuity Platform declaratively using the [Akuity CLI](/akuity-portal/automation). 3. Clone the akuity/declarative-example repo to your machine. ## Sign up for the Akuity Platform :::tip [Sign up](https://hubs.li/Q02l2Xdj0) for a free 14-day trial of the Akuity Platform! ::: If you haven't already, sign up to [create your account](/argocd/getting-started/create-argo-cd-instance#account-setup) on the Akuity Platform and create an organization. ## Log into the `akuity` CLI ``` akuity login ``` - Open the link displayed, enter the code. ## Set your organization name in the `akuity` config ``` akuity config set --organization-name= ``` :::warning Replace `` with your organization's name. ::: ## Create the Argo CD instance on the Akuity Platform ``` akuity argocd apply -f akuity-platform/example ``` This will create an Argo CD instance based the definition in the [`argocd.yaml`](https://github.com/akuity/declarative-example/blob/main/akuity-platform/example/argocd.yaml) manifest, and the configurations in the [`argocd-cm.yaml`](https://github.com/akuity/declarative-example/blob/main/akuity-platform/example/argocd-cm.yaml) and [`argocd-secret.yaml`](https://github.com/akuity/declarative-example/blob/main/akuity-platform/example/argocd-secret.yaml) (which follow the same format as the open-source). The [`cluster.yaml`](https://github.com/akuity/declarative-example/blob/main/akuity-platform/example/cluster.yaml) manifest contains the configuration for provisioning an agent that will connect a Kubernetes cluster to the Argo CD instance. In the next step, you'll install the agent into the cluster. The `Application` in the [`bootstrap-app.yaml`](https://github.com/akuity/declarative-example/blob/main/akuity-platform/example/bootstrap-app.yaml) manifest will also be deployed. Following [the App of Apps pattern](https://www.youtube.com/watch?v=2pvGL0zqf9o), it points to a folder containing other `Applications` and `ApplicationSets`, therefore automatically bootstrapping your Argo CD instance. The `Applications` deployed by the `bootstrap` `Application` may appear in an `Unknown` sync status due to the unavailable destination cluster at the time of creation. After completing the next step, they will eventually retry (up to 5 minutes) and sync successfully. You can speed this up by clicking refresh after the agent has become healthy on the cluster. :::info View the instance in the UI at (replacing `` with your organization name): ``` https://akuity.cloud//argocd/example ``` ::: :::tip The `akuity argocd apply -f` command can apply a folder containing only `Applications`, `ApplicationSets`, and `AppProjects` without including an Argo CD definition by specifying the instance name with `--name`. ``` akuity argocd apply -f apps/ --name example ``` ::: ## Connect The Clusters Apply the agent install manifests to the cluster. ``` akuity argocd cluster get-agent-manifests --instance-name=example kind | kubectl apply -f - ``` :::tip Check the progress of the agent installation with `kubectl get pods -n akuity`. ::: ## Log Into The `argocd` CLI ``` argocd login \ $(akuity argocd instance get example -o json | jq -r '.id').cd.akuity.cloud \ --username admin \ --password akuity-argocd \ --grpc-web ``` :::info The second line includes a sub-command which is used to form the server URL of your Argo CD instance. - `akuity argocd instance get example -o json` will retrieve the Argo CD instance named `example` from your organization on the Akuity Platform and output the metadata in JSON. - The output is then piped to `jq -r '.id'`. We use `jq` here to filter the JSON output down to the `.id` attribute for the `example` Argo CD instance. - This is all encapsulated in `$(...)` which allows us to use the id as the sub-domain of the FQDN `.cd.akuity.cloud` for the server URL in the `argocd login` command. ::: :::tip The admin password is set to `akuity-argocd` in the [`argocd-secret.yaml`](https://github.com/akuity/declarative-example/blob/main/akuity-platform/example/argocd-secret.yaml) manifest. ::: ## List The `Applications` ``` argocd app list ``` Example output: ``` NAME CLUSTER NAMESPACE PROJECT STATUS HEALTH SYNCPOLICY CONDITIONS REPO PATH TARGET argocd/bootstrap in-cluster argocd default Synced Healthy Auto-Prune https://github.com/akuity/declarative-example apps/ HEAD argocd/helm-guestbook kind helm-guestbook default Synced Healthy Auto-Prune https://github.com/morey-tech/argocd-example-apps general/helm-guestbook HEAD argocd/sync-waves kind sync-waves default Synced Healthy Auto-Prune https://github.com/morey-tech/argocd-example-apps general/sync-waves HEAD ``` ## Next Steps Congratulations! You have now have a production-ready Argo CD instance that is managed fully declaratively without any concern for the underlying infrastructure. If you are just starting out with Argo CD, consider using your new Argo CD instance to complete our [Introduction to Argo CD tutorial](/tutorials/intro-to-argo-cd/). However, if you are experienced but looking to expand you skills, check out our [Advanced GitOps Workshop](/tutorials/adv-gitops/). --- ## GitHub Commit Status Notifications for Argo CD Notifications can be self-implemented by Argo CD users, for example, by using [Resource Hooks](https://argo-cd.readthedocs.io/en/stable/user-guide/resource_hooks/). The hook is a pod that runs before or after the `Application` is synced, making it convenient for sending a notification. However, this requires every engineer to find answers to questions like: * How to get the notification service credentials? * Where to store the credentials? * What should be a notifiction message? * Where to send it? Most answers are the same for every team except notification destinations. That is why it is better to leverage the [Argo CD Notifications](https://argo-cd.readthedocs.io/en/stable/operator-manual/notifications/) controller that enables configuring notifications in a centralized way and for end users to specify where and when to send notifications. :::tip If you haven't already created an Argo CD instance, [sign up for a 14-day free trial](https://hubs.li/Q02l2Xm10) of the Akuity Platform and check out [our Getting Started guide](/argocd/getting-started/create-argo-cd-instance)! ::: ## 1. Setting Up the GitHub Notification Service Argo CD Notifications supports integration with [various notification services](https://argo-cd.readthedocs.io/en/stable/operator-manual/notifications/services/overview/) like [Slack](https://argo-cd.readthedocs.io/en/stable/operator-manual/notifications/services/slack/), [PagerDuty](https://argo-cd.readthedocs.io/en/stable/operator-manual/notifications/services/pagerduty/), [OpsGenie](https://argo-cd.readthedocs.io/en/stable/operator-manual/notifications/services/opsgenie/) and more. Typical examples are sending Slack or Email notifications; however, this tutorial will use the GitHub service to add Argo CD to commit statuses. 1. [Create a new GitHub App](https://github.com/settings/apps/new). - Set GitHub App name to `argocd-notifications-`, replacing `` with your GitHub username. :::caution GitHub App names are globally unique, so including the `` is essential. ::: - Set Homepage URL to `https://.cd.akuity.cloud/`, replacing `` with the ID for the Argo CD instance on the Akuity Platform. ``` https://.cd.akuity.cloud/ ``` ![akuity-argo-cd-instance-id](./akuity-argo-cd-instance-id.png) - Set Authorization callback URL to `https://.cd.akuity.cloud/api/dex/callback`, replacing `` with the ID for the Argo CD instance on the Akuity Platform. ``` https://.cd.akuity.cloud/api/dex/callback ``` :::note `` is used as a default placeholder for demo purposes when you first create your instance on the Akuity Platform. However, the actual URL can be customized and set to anything, depending on how you configure your Akuity sub-domain or FQDN. ::: - Under the "Webhook" section, **deselect** the Active option. - Under the "Permissions" section, expand the Repository permissions > Commit statuses, select the `Read and write` access level. - Click Create GitHub App. 2. Generate a private key for the GitHub App. - Navigate to: `https://github.com/settings/apps/argocd-notifications-`, replacing `` with your GitHub username. - Under Private keys, click Generate a private key. - The `.pem` file containing the private key will download to your machine. 3. Install the GitHub App in your GitOps repo. - Navigate to `https://github.com/settings/apps/argocd-notifications-/installations`, replacing `` with your GitHub username. - Click Install. - Select Only select repositories. - Select your GitOps repo. - Click Install. - Copy the installation ID from the URL ``` https://github.com/settings/installations/ ``` 4. Configure the notification service in the settings for the Argo CD instance on the Akuity Platform. - From the Argo CD instance on the Akuity Platform, navigate to Settings > Notifications. - Go to the YAML Editor tab. - Paste the following snippet replacing: - `` with the App ID in the settings of the GitHub App. - `` with the value copied from the installation URL in the previous step. ```yaml service.github: | appID: installationID: privateKey: $github-privateKey trigger.on-deployed: | - description: Application is synced and healthy. Triggered once per commit. oncePer: app.status.operationState.syncResult.revision send: - app-deployed when: app.status.operationState.phase in ['Succeeded'] and app.status.health.status == 'Healthy' template.app-deployed: > message: | Application {{.app.metadata.name}} is now running new version of deployments manifests. github: status: state: success label: "argo-cd/{{.app.metadata.name}}" targetURL: "{{.context.argocdUrl}}/applications/{{.app.metadata.name}}?operation=true" ``` - Go to the Secrets tab. - Add the key `github-privateKey` and paste the contents of the `.pem` file containing the Private Key for the GitHub App as the value. - Click Save. You can think about triggers as a function that continuously checks the Argo CD application state and returns `true` if the notification should be sent. The notification is sent when trigger's return value changes from `false` to `true` so that the user gets notified about an event only once when it happens. ```yaml trigger.on-deployed: | - description: Application is synced and healthy. Triggered once per commit. oncePer: app.status.operationState.syncResult.revision send: - app-deployed when: app.status.operationState.phase in ['Succeeded'] and app.status.health.status == 'Healthy' ``` In the triggers configuration, you might notice the `send` field. This field specifies the notification template that should be used to generate the notification content. ```yaml template.app-deployed: > message: | Application {{.app.metadata.name}} is now running new version of deployments manifests. github: status: state: success label: "argo-cd/{{.app.metadata.name}}" targetURL: "{{.context.argocdUrl}}/applications/{{.app.metadata.name}}?operation=true" ``` Templates are using [Go templates](https://golang.org/pkg/text/template/) syntax. The template configuration includes the `message` field that is common for all notification services. You might configure service-specific fields like `email.subject` or `slack.attachements` for customized notifications for each notification service. ## 2. Adding the Notification Subscription Once templates and notifications are configured in Argo CD, the end users must create a subscription. To subscribe to notifications, add the following annotation to your `Application`: 1. To subscribe to "notifications" (setting commit statues), open the `Application` manifest in your GitOps repo, or edit it in the Argo CD UI. 2. Add the following annotation to the `metadata` of the `Application`: ```yaml metadata: annotations: notifications.argoproj.io/subscribe.on-deployed.github: "" ``` 3. Commit and push the changes to the repo. Go ahead and trigger a change in the source of your `Application`. Once the new image has been built, the rendered manifests are updated on the GitOps repo, and the `Application` has been synced and healthy, the commit will show a status check with a link to the operation in Argo CD. ![Commit Status Check using GitHub Notification Service](commit-status-check.png) ## Next Steps Congratulations! You have now have the GitHub commit status links back to the related Argo CD `Application`. If you are just starting out with Argo CD, consider using your new Argo CD instance to complete our [Introduction to Argo CD tutorial](/tutorials/intro-to-argo-cd/). However, if you are experienced but looking to expand you skills, check out our [Advanced GitOps Workshop](/tutorials/adv-gitops/). --- ## Installing the Akuity Agent on Amazon EKS with the Akuity EKS add-on You can install the Akuity Agent on an Amazon EKS cluster by installing the Agent as an Amazon EKS add-on. Compared to the regular Agent installation, there is a difference when installing as an add-on. During EKS add-on installation, images must be pulled only from the EKS repository. This can’t be changed by the user. ## Prerequisites * An [Akuity Platform](https://akuity.cloud) account with an Argo CD instance * An AWS EKS cluster * Subscription to the Akuity Agent EKS add-on * kubectl installed * If you are using the command line interface for setting up the add-on, AWS CLI ## Adding an AWS EKS Cluster to your Akuity Argo CD instance 1. Navigate to Argo CD → your instance → Clusters. 2. Click + Connect a cluster to add a Kubernetes cluster. 3. Input your Cluster Name. 4. Expand the "Advanced settings" section 5. Click on "Addons" tab 6. Click on the "+ Add" button for EKS Add-on 7. Click Connect Cluster. ![eks_addon_aws_console_1](./eks_addon_akp_cluster_add_1.png) This will take you to an Install Akuity Agent pop-up screen. Make sure you are on the "EKS" tab and then select which way you want to install the Add-on you can pick the AWS console or the CLI. ### Create the `akuity` namespace ```bash kubectl create namespace akuity ``` **AWS Console** ### AWS Console * Go to the EKS cluster in the AWS console. * Go to the add-on tab and select *Get more add-ons*. * Find and select *Akuity Agent*. Then follow the prompts to complete the installation. ![eks_addon_aws_console_1](./eks_addon_aws_console_1.png) Go to the Akuity Platform's Cluster page and copy the JSON from Step 1. ![eks_addon_aws_console_1](./eks_addon_akp_cluster_add_2.png) It will look something like this. ```JSON { "akpUrl": "https://akuity.cloud/api/v1/orgs/yx8wvj7x/argocd/instances/ssvo50jge/clusters/923arp4j/manifests" } ``` Select the latest version, and expand the "Optional configuration settings" so that you can copy the JSON from above into the "Configuration values" box. Select the "Override" radio button and then hit "Next". ![eks_addon_aws_console_1](./eks_addon_aws_console_2.png) If everything looks good, click the "Create" button. ![eks_addon_aws_console_1](./eks_addon_aws_console_3.png) **CLI** ### CLI #### Install the Akuity Agent add-on * In the Install Akuity Agent pop-up screen, enter the name of your EKS cluster, and then click "Copy to Clipboard" on step 2. ![eks_addon_aws_console_1](./eks_addon_akp_cluster_add_3.png) * Paste the copied command into your terminal and run it to apply the agent manifest. It will look something like this ```bash export AKP_API_URL="" aws eks create-addon --cluster-name my-cluster --addon-name akuity_agent \ --configuration-values "{\"akpUrl\":\"$AKP_API_URL\"}" --resolve-conflicts OVERWRITE ``` ### Create the secret for our API token * In the Install Akuity Agent pop-up screen, click "Copy to Clipboard" on the bottom of the page. * Paste the copied command into your terminal and run it to apply the agent manifest. It will look something like this. ```bash export TOKEN= kubectl create secret generic akuity-platform-api-token -n akuity --from-literal=AKP_TOKEN="$TOKEN" ``` ### EKS Add-on status Add-on installation is asynchronous. To check installation status, run: ```bash aws eks describe-addon --addon-name akuity_agent --region --cluster-name ``` To verify that the installation was successful, view the cluster status in Akuity platform to make sure the cluster agent is up and running. ### Remove the secret Once the Akuity EKS Add-on is up and running the `akuity-platform-api-token` secret is no longer needed, and should be deleted : ```bash kubectl delete secret akuity-platform-api-token -n akuity ``` ## Uninstall the Akuity Agent EKS add-on ### Remove the secret If you want to uninstall the Akuity Agent, make sure the `akuity-platform-api-token` secret is deleted : ```bash kubectl delete secret akuity-platform-api-token -n akuity ``` Confirm the secret is deleted and proceed with removing the Akuity agent: ### Remove the Akuity agent 1. Go to the akuity platform's Cluster management page for your Instance and click the delete button for the cluster you want to remove the agent from. 2. Don't check "Yes, delete cluster installation namespace" checkbox, leave it unchecked. 3. Click the "Copy to clipboard" button and paste the commands into the CLI to remove the agent from your cluster. 3. Confirm that you want to remove the cluster. This should remove the Akuity agent from your cluster and you can proceed with removing the EKS add-on **AWS Console** ### AWS Console * Go to the EKS cluster in the AWS console. * Go to the add-on tab and select the *Akuity Agent* add-on. * Click **Remove** and confirm when prompted. **CLI** ### CLI To delete the add-on, run: ```bash aws eks delete-addon --addon-name akuity_agent --region --cluster-name ``` **Note:** If you uninstall the Akuity Agent add-on before deleting the resources, The Agent continues to run on the cluster. Deleting the namespace fails since the `Agent` cannot be finalized without a running Operator. --- ## Kargo Quickstart This quickstart will walk you through implementing Kargo with the Akuity Platform, to manage the promotion of applications in a declarative fashion. After completing this tutorial, you will have a Kubernetes cluster, with Applications deployed using an Argo CD control plane, and environment promotions managed by Kargo. - [1. Prerequisites](#1-prerequisites) - [1.1. GitHub PAT Setup](#11-github-pat-setup) - [2. Setting up Your Environment](#2-setting-up-your-environment) - [2.1. Create the Repository from a Template](#21-create-the-repository-from-a-template) - [2.1.1. Verify Environment](#211-verify-environment) - [2.1.2. Create Image Repository](#212-create-image-repository) - [2.2. Akuity Platform Sign Up](#22-akuity-platform-sign-up) - [2.3. Create a Kargo Instance](#23-create-a-kargo-instance) - [2.4. Connect a Kargo Agent](#24-connect-a-kargo-agent) - [2.5. Enable the Kargo admin Account](#25-enable-the-kargo-admin-account) - [2.6. Accessing Kargo](#26-accessing-kargo) - [2.6.1. Kargo Web UI](#261-kargo-web-ui) - [2.6.2. Kargo CLI](#262-kargo-cli) - [3. Using Kargo For Promotions](#3-using-kargo-for-promotions) - [3.1. Adding Repository Secret](#31-adding-repository-secret) - [3.2. Kargo Setup](#32-kargo-setup) - [3.2.1. Kargo Project](#321-kargo-project) - [3.2.2. Kargo Warehouse](#322-kargo-warehouse) - [3.2.3. Kargo Stages](#323-kargo-stages) - [3.3. Promoting with Kargo](#33-promoting-with-kargo) - [3.3.1. Image Promotion](#331-image-promotion) - [3.3.2. Promoting Image Update](#332-promoting-image-update) - [3.3.3. Pull Request Promotions](#333-pull-request-promotions) - [4. Integrating Argo CD](#4-integrating-argo-cd) - [4.1. Making the Image Public](#41-making-the-image-public) - [4.2. Creating an Argo CD Instance](#42-creating-an-argo-cd-instance) - [4.3. Kargo Integration](#43-kargo-integration) - [4.3.1. Kargo Agent Setup](#431-kargo-agent-setup) - [4.3.2. Update Kargo Stages](#432-update-kargo-stages) - [4.3. Promoting with Kargo](#43-promoting-with-kargo) - [5. Summary](#5-summary) ## 1. Prerequisites To follow this tutorial make sure you have minimal working knowledge of the following concepts: - [Kubernetes](https://youtu.be/4ht22ReBjno?t=164) - [GitOps](https://akuity.io/gitops) - [Argo CD](https://argo-cd.readthedocs.io) The tutorial requires that you also have a [GitHub](https://github.com/) Account. You will use it to: - host a **public** repo for Argo CD and Kargo - utilize [GitHub Codespaces](https://github.com/features/codespaces) for the workshop environment. Ensure that you have a quota available. The free tier includes 4 vCPU at 30 hours a month. - create a free account on the [Akuity Platform](https://akuity.cloud/). The tutorial was written and tested using the following tool and component versions: - Argo CD: v2.10.1 - Kargo: v0.5.2 - Docker Desktop: 4.13.1 - Kubernertes: v1.29.1 - kind: v0.22.0 ### 1.1. GitHub PAT Setup A GitHub Personal Access Token (PAT), is needed for creating/updating/pushing images and image changes to the GitHub Container Registry (ghcr). Kargo also needs this PAT to write back changes to the GitHub repo we will be working with. 1. Navigate to [https://github.com/settings/tokens/new](https://github.com/settings/tokens/new). - Or from the UI: - https://github.com/settings/profile - `Developer settings` at the bottom of the left hand menu - `Personal access tokens` -> `Tokens (classic)` - `Generate new token` -> `Generate new token (classic)` 2. Set Note to `kargo-quickstart`. 3. Set the Expiration to `7 days`. 4. Under "Select scopes", select: - `repo` - `write:packages` - `user:email` 5. Click Generate token at the bottom of the page. 6. Copy the generated PAT. ## 2. Setting up Your Environment In this section, you will be setting up your test environment using GitHub Codespaces and setting up an account on the Akuity Platform. ### 2.1. Create the Repository from a Template We have created a sample repo that holds everything you need in order to get started with Kargo. We will also be using this repo in a Codespace as a test environment. 1. Click [this link](https://github.com/akuity/kargo-quickstart-template/generate) or click "Use this template" from the [`https://github.com/akuity/kargo-quickstart-template`](https://github.com/akuity/kargo-quickstart-template) repo main page. 2. Ensure the desired "Owner" is selected (e.g., your account and not an organization). 3. Enter a unique name for the "Repository name". 4. Then click Create repository from template. 5. Next, you will start a new Codespace by clicking the green Code button on the repo page, selecting the Codespaces tab, and then selecting Create codespace on main. :::warning If you have other Codespaces running, you may run into usage limits. Shutdown Codespaces that you are not using, while doing this tutorial. ::: The Codespace will open in another browser tab with information about the progress of setting it up. Once it is done, you should see a terminal in the browser with the repo open. #### 2.1.1. Verify Environment Part of the Codespace setup was to install all necessary tools, which includes setting up `kind`, `kubectl`, and `kargo` cli tools. You can verify that the environment is ready by going through the following steps: 1. Verify that `k3d` is installed and running a Kubernetes cluster. ``` k3d cluster list ``` You should see the following output: ``` NAME SERVERS AGENTS LOADBALANCER kargo-quickstart 1/1 0/0 true ``` 2. Check that the cluster works by running `kubectl get nodes`. ``` % kubectl get nodes NAME STATUS ROLES AGE VERSION k3d-kargo-quickstart-server-0 Ready control-plane,master 64s v1.28.8+k3s1 ``` Fetching the nodes will demonstrate that `kubectl` can connect to the cluster and query the API server. The node should be in the "Ready" status. 3. Export your GitHub PAT in the `KARGO_QUICKSTART_PAT` environment variable. ``` export KARGO_QUICKSTART_PAT= ``` You will be using your GitHub PAT later in this tutorial. #### 2.1.2. Create Image Repository This tutorial will show you how to promote image updates with Kargo. This means we will be using an image in your GitHub Container Registry (ghcr). :::warning The [free tier of ghcr](https://github.com/features/packages#pricing) is capped at `500MB` images. This is enough for what you are going to be testing with. If you run into any issues, please check your `Packages` tab in your GitHub account page found on `https://github.com/` ::: The easiest way to create a new ghcr.io image repository is by retagging/pushing an existing image with your GitHub username. 1. Login to `ghcr` using your GitHub Username and your GitHub PAT ``` docker login --username ${GITHUB_USER} --password ${KARGO_QUICKSTART_PAT} ghcr.io ``` 2. Create the example image in your account using the `docker buildx imagetools` command. ``` docker buildx imagetools create ghcr.io/akuity/guestbook:latest -t ghcr.io/${GITHUB_USER}/guestbook:v0.0.1 ``` You will now have a guestbook container image repository `https://github.com/users/${GITHUB_USER}/packages/container/package/guestbook` ### 2.2. Akuity Platform Sign Up In this scenario you will sign up for the Akuity Platform and create a Kargo instance. As GitHub is being used to host our sample environment, the Akuity Platform will be used to host our Kargo instance. To do that, you will have to sign up for a free trial. :::tip [Sign up for a free 30-day trial of the Akuity Platform!](https://akuity.cloud/) ::: 1. Create an account on the [Akuity Platform](https://akuity.cloud/). 2. To log in with GitHub SSO, click "Continue with GitHub". :::note You can also use Google SSO or an email and password combination. ::: 3. Set up an Organization. Before you create a Kargo instance, you will need to create an organization (if you do not already have one). 4. Click the create or join link. 5. Click + New organization in the upper right-hand corner of the dashboard. 6. Name your organization following the rules listed below the Organization Name field. ### 2.3. Create a Kargo Instance 1. Navigate to Kargo. 2. Click + Create in the upper right-hand corner of the dashboard. 3. Name your instance following the rules listed below the Instance Name field. 4. (Optionally) Choose the Kargo version you want to use. It is recommended to use the default one. 5. Click Create. It will take several seconds to create your new Kargo instance (See Progressing status next to your new instance's name), so please be patient. ### 2.4. Connect a Kargo Agent After your new Kargo instance is created successfully ( See Healthy status next to your new instance's name), you will need to register an agent. 1. Navigate to Kargo → _your instance_ → Agents. 2. Click + Register an agent to add a Kargo Agent. 3. Input your Agent Name. 4. Leave Self-hosted Kargo Agent disabled. :::note You can also self-host the Kargo agent on your own Kubernetes cluster. This is usually needed when your cluster is behind a firewall. You do this by enabling the _Self-hosted Kargo Agent_ option. Select the self-hosted agent option if Kargo needs to run Kubernetes Jobs as part of testing/verification, or if Kargo needs to interface with private, self-hosted services including: - private Git servers - internally accessible metric providers (e.g. self-hosted Prometheus) - self-managed Argo CD ::: 5. Leave Akuity Managed Argo CD empty for now. :::note Kargo can interface with Argo CD instances to sync applications, reflect application health, and verify successful sync operations during promotion. ::: 6. Leave Set as Default Shard enabled. 7. Click Connect. After installing the agent into your Kargo instance, you should see the agent listed in the Akuity dashboard go from `Progressing` to a green heart icon with the status of `Healthy` next to the agent name. ### 2.5. Enable the Kargo admin Account The Kargo instances you create inside the Akuity Platform do not enable the `admin` user by default. For this tutorial, we will need to enable the `admin` account. To enable the `admin` user on a Kargo instance: 1. Navigate to Kargo → _your instance_ → Settings → System Accounts. 1. Enable the Admin Account switch. 1. Specify a custom password and click Save ### 2.6. Accessing Kargo Kargo comes with a feature-rich web UI that can be used to manage and visualize your CD pipelines. We will be using both the web-based UI and CLI to interact with Kargo. #### 2.6.1. Kargo Web UI ![Kargo Instance URL](./kargo-instance-url.png) 1. Click on the _instance-id_.kargo.akuity.cloud. 2. Log in with the username `admin` and the password set in the [enabling the `admin` user](#25-enable-the-kargo-admin-account) section. #### 2.6.2. Kargo CLI Since the `kargo` CLI is going to be used, we will need to set it up. The `kargo` CLI is already preinstalled in the Codespace. You can log in by using the `kargo login` command. ``` kargo login \ --admin \ --password ``` ## 3. Using Kargo For Promotions Kargo handles promotion by monitoring repositories (Git, Image, Helm) for changes and making the necessary commits to your Git repository, leaving the reconciliation to the Argo CD GitOps controller. Furthermore, Kargo will also verify these promotions once they are deployed. :::tip For more information about Kargo and the concepts behind it, please see the [official documentation](https://kargo.akuity.io/concepts) ::: In the following sections, you will explore how Kargo handles stage-to-stage promotions using GitOps. ### 3.1. Adding Repository Secret In order for Kargo to manage the progression of `Freight` from stage to stage, Kargo will often require read/write permissions on private GitOps repositories and read-only permissions on private container image and/or Helm chart repositories. Also, Kargo has a concept called a Project. A Project is a collection of related Kargo resources that describe one or more delivery pipelines and is the basic unit of organization and tenancy in Kargo. It is also where credentials are scoped. Since Kargo needs to write back to the Git repository, it will need access to the GitHub PAT to interact with it. :::warning Make sure you are logged-in to the Kargo API as described in the [Kargo CLI section](#261-kargo-web-ui) ::: 1. Create a Kargo Project called `kargo-simple` ``` kargo create project kargo-simple ``` 2. Create Git credentials with the `kargo` CLI in the `kargo-simple` project. ``` kargo create repo-credentials github-creds \ --project kargo-simple --git \ --username ${GITHUB_USER} --password ${KARGO_QUICKSTART_PAT} \ --repo-url https://github.com/${GITHUB_REPOSITORY} ``` 3. Create Image credentials with the `kargo` CLI in the `kargo-simple` project. ``` kargo create repo-credentials ghcr-creds \ --project kargo-simple --image \ --username ${GITHUB_USER} --password ${KARGO_QUICKSTART_PAT} \ --repo-url ghcr.io/${GITHUB_USER}/guestbook ``` ### 3.2. Kargo Setup This section focuses on getting Kargo-specific objects created. In the end of this section, you will have a CD Pipeline made possible by Kargo primitives that will be set up along this section of this quickstart tutorial. In the end, there will be a `Project` (which we covered in the previous section), `Warehouse`, and `Stage`s #### 3.2.1. Kargo Project In the section where [your GitHub PAT was added to Kargo](#31-adding-repository-secret), we went through the concept of a `Project`. To reiterate, a Kargo `Project` is a logical collection of related objects; it is also the basic level of organization and tenancy. Furthermore, RBAC rules are also defined at the project level and project administrators may use projects to define policies, such as whether a stage is eligible for automatic promotions of new freight. In the previous section a Kargo *Project* called `kargo-simple` was created using the `kargo` CLI; and a walkthrough how you can create a Project in the Kargo UI was also demonstrated. However, you can also create a Project declaratively. In the root of the Git repository you created based on the template, you should see the following file [kargo/project.yaml](https://github.com/akuity/kargo-quickstart-template/blob/main/kargo/project.yaml). ```yaml apiVersion: kargo.akuity.io/v1alpha1 kind: Project metadata: name: kargo-simple ``` Applying this declaratively, would look something like this. 1. Ensure you are logged into your Kargo instance ``` kargo login \ --admin \ --password ``` 2. Create Git credentials with the `kargo` CLI in the `kargo-simple` project. ``` kargo apply -f ./kargo/project.yaml ``` :::tip 💡 It is OK to run `kargo apply` even if you have already created the `Project` ::: You should be able to see the `kargo-simple` listed when you run the `kargo get projects` command. ``` $ kargo get projects NAME PHASE AGE kargo-simple Ready 22h ``` #### 3.2.2. Kargo Warehouse A Kargo `Warehouse` is where promotable artifacts are staged before they move into the CD Pipeline. Before we get into what a `Warehouse` is, it is important that you know what a `Freight` is. `Freight` is a set of references to one or more versioned artifacts, which may include one or more Container Images, Kubernetes Manifests from Git, and/or Helm Charts. A collection of these versioned artifacts is what is known as `Freight`, and it is promoted together as a single promotable unit. You can think of `Freight` as a "meta-artifact". Now that you are familiar with `Freight`, you can understand what a Kargo `Warehouse` is. A `Warehouse` not only stages `Freight`, but it also defines where this `Freight` comes from via a subscription. A subscription defines where a particular artifact comes from along with any filtering rules. In the root of the Git repository you created based on the template, you should see the following `Warehouse` file [kargo/warehouse.yaml](https://github.com/akuity/kargo-quickstart-template/blob/main/kargo/warehouse.yaml). ```yaml apiVersion: kargo.akuity.io/v1alpha1 kind: Warehouse metadata: name: guestbook namespace: kargo-simple spec: subscriptions: - image: repoURL: ghcr.io/${GITHUB_USER}/guestbook tagSelectionStrategy: SemVer ``` In this scenario, the `Warehouse` will be subscribed to the `ghcr` image repo we created earlier. We are using a filtering rule of `tagSelectionStrategy` set to `SemVer`, meaning that Kargo will only look for new images that are tagged using [Semantic Versioning](https://semver.org) :::tip For more information about [Warehouse filtering rules](https://doc.crds.dev/github.com/akuity/kargo/kargo.akuity.io/Warehouse/v1alpha1) see the official documentation. ::: 1. Create the `Warehouse` by applying the manifest in your repository. ``` kargo apply -f ./kargo/warehouse.yaml ``` 2. Verify that the `Warehouse` was created with the `kargo get warehouses` command. ``` kargo get warehouses --project kargo-simple NAME SHARD AGE guestbook 14m ``` #### 3.2.3. Kargo Stages Kargo `Stage`s are a key component to a Kargo CD Pipeline. With traditional CI/CD pipelines, the objective is to promote something from environment to environment. When you hear the term "environment", what you envision will depend significantly on your perspective. A developer may think "It's this specific version of the app that's running" and someone in Operations may think "It's a collection of VPCs, Firewall Rules, and a Region in the Cloud". To eliminate confusion, Kargo avoids the term "environment" altogether in favor of stage. The important feature of a stage is that its name ("test" or "prod," for instance) denotes an application instance's purpose and not necessarily its location. :::tip 💡 [Read more about the "stage vs environment" question](https://akuity.io/blog/kargo-stage-not-environment/) ::: What is important to note is that a Kargo CD Pipelines are created by linking `Stage`s and `Warehouse`s together to create a [DAG](https://en.wikipedia.org/wiki/Directed_acyclic_graph) for your delivery pipeline. Promotion of artifacts moves them into their respective `Stage`s by verifying that they were promoted successfully in the previous step. In short: * `Stage`s subscribe to a `Warehouse` to get promotable artifacts * `Stage`s can also subscribe to one or many _other_ `Stage`(s) to get those same artifacts. In the root of the Git repository you created based on the template, you should see the following `Stage`s file [kargo/stages.yaml](https://github.com/akuity/kargo-quickstart-template/blob/main/kargo/stages.yaml). Take a look at the first `Stage` called `dev` ```yaml apiVersion: kargo.akuity.io/v1alpha1 kind: Stage metadata: name: dev namespace: kargo-simple annotations: kargo.akuity.io/color: red spec: requestedFreight: - origin: kind: Warehouse name: guestbook sources: direct: true promotionMechanisms: gitRepoUpdates: - repoURL: https://github.com/${GITHUB_USER}/${GITHUB_REPO} writeBranch: main kustomize: images: - image: ghcr.io/${GITHUB_USER}/guestbook path: app/env/dev ``` Here, the `dev` `Stage` is subscribed to the `Warehouse` we just created (where the `Warehouse` is subscribed to the Image repository). When the artifacts are promoted, Kargo runs a `kustomize edit set image` (denoted in the `.spec.promotionMechanisms`) in the specified Git repository to the specified path. In short, Kargo commits new image versions back into a respository. The `dev` `Stage` gets its artifacts from the `Warehouse`; but the downstream `Stage`s get those same artifacts presented to them only by subscribing to each other. For example, the `staging` `Stage` is subscribed to the `dev` `Stage` ```yaml apiVersion: kargo.akuity.io/v1alpha1 kind: Stage metadata: name: staging namespace: kargo-simple annotations: kargo.akuity.io/color: amber spec: requestedFreight: - origin: kind: Warehouse name: guestbook sources: stages: - dev # ...snip ``` And the `prod` `Stage` is subscribed to the `staging` `Stage` ```yaml apiVersion: kargo.akuity.io/v1alpha1 kind: Stage metadata: name: prod namespace: kargo-simple annotations: kargo.akuity.io/color: violet spec: requestedFreight: - origin: kind: Warehouse name: guestbook sources: stages: - staging promotionMechanisms: gitRepoUpdates: - repoURL: https://github.com/${GITHUB_USER}/${GITHUB_REPO} writeBranch: main kustomize: images: - image: ghcr.io/${GITHUB_USER}/guestbook path: app/env/prod pullRequest: {} ``` Another thing to notice is that the `prod` `Stage` is configured to create a pull request, instead of committing directly to the tracked branch. We will go over this in a later section of this tutorial. 1. To create the `Stage`s, apply the manifest in your repository. ``` kargo apply -f kargo/stages.yaml ``` 2. Verify that the `Stage`s were created with the `kargo get stages` command. ``` kargo get stages --project kargo-simple NAME SHARD CURRENT FREIGHT HEALTH PHASE AGE dev NotApplicable 20s staging NotApplicable 20s prod NotApplicable 20s ``` :::tip The `SHARD` column shows which agent is reconciling each Stage. Stages without a shard assignment use the default shard. To assign a Stage to a specific agent, set `spec.shard` in your Stage manifest. This is particularly important for Stages with verification that require in-cluster resources. See [Shards and Agents](../../04-kargo/03-managing-instances/20-agents/30-shards-and-agents.md) for more information. ::: You should see all 3 stages created. When you look at the Kargo UI, you should see the following ![Kargo DAG Screenshot](https://media.supademo.com/clllc86o439ggt419xa8ertos/wJzao4aReAul9myzoKZWp.jpeg) ### 3.3. Promoting with Kargo In this section we will be promoting the image we created in the `ghcr` repo in the [Create Image Repository](#212-create-image-repository) section. #### 3.3.1. Image Promotion In this section we will be using Kargo to promote [the image you created earlier](#212-create-image-repository). After you navigate to your Kago instance UI: 1. Click on your `kargo-simple` *Project*. 2. Click on the icon on the `dev` `Stage` to initiate promotion. 3. Click on the available freight (there should only be one). 4. Click on `YES` to confirm promotion 5. The promotion will be progressing as indicated by the icon. 6. When checking your Git repository, you will notice that Kargo committed back to the repository using `kustomize`. 7. In the Kargo UI, repeat the steps to promote the freight into the `staging` `Stage`. 8. Note that the freight will be color-coded to show which stage the artifacts are in. #### 3.3.2. Promoting Image Update Now we will simulate a release and use Kargo to promote that update using the same CD Pipeline. 1. To simulate a release, simply retag an image with a newer semantic version using the `docker buildx imagetools` command. ``` docker buildx imagetools create ghcr.io/akuity/guestbook:latest -t ghcr.io/${GITHUB_USER}/guestbook:v0.0.2 ``` 2. On the Kargo UI, click on the `Refresh` button on the `Warehouse` to tell Kargo to fetch more `Freight`. :::info Kargo will produce `Freight` even if you don't refresh since Kargo runs a loop to check for new `Freight`! ::: 3. Click on the icon on the `dev` `Stage` to initiate promotion. 4. Click on the newly available `Freight` (tagged with `v0.0.2` that you just created) 5. Click on `YES` to confirm promotion 6. The promotion will be progressing as indicated by the icon. 7. Note that the new `Freight` will be color-coded to show which stage the artifacts are in. #### 3.3.3. Pull Request Promotions In the [Kargo Stages](#323-kargo-stages) section, you had an overview of what a `Stage` is and how it is used for promotions. Specifically, how Kargo commits changes back to the specified Git repository. You can also configure the `Stage` to have Kargo submit a PR instead of a direct commit. Taking another look at the `Stage`s file [kargo/stages.yaml](https://github.com/akuity/kargo-quickstart-template/blob/main/kargo/stages.yaml). You will see the following in the `prod` `Stage`. ```yaml spec: promotionMechanisms: gitRepoUpdates: - repoURL: https://github.com/ # snipped for brevity pullRequest: {} ``` Part of the configuration has the `pullRequest` option, which instructs Kargo to perform a pull request instead of directly commiting. In this seciton, you will see how this works. 1. Click on the icon on the `prod` `Stage` to initiate promotion. 2. Note that only freight that has been verified in the `staging` `Stage` is available for `prod`. 3. Click on the available freight. 4. Click on `YES` to confirm promotion 5. The promotion will be progressing as indicated by the icon. 6. Navigate to your Git repository and click on *Pull requests* 7. Note that a new pull request was created - merge it. 8. Navigate back to the Kargo UI and see that the `Freight` is now in the `prod` `Stage`. ## 4. Integrating Argo CD So far, you have been working on Kargo on its own. The real power comes from using Kargo with a GitOps controller (which does the deployment). In this section, Kargo will be integrated with Argo CD to demonstrate an end-to-end GitOps Continuous Promotion pipeline. ### 4.1. Making the Image Public When you created the `ghcr.io/${GITHUB_USER}/guestbook` image in the [Create Image Repository](#212-create-image-repository) section, that image (by default) has its visibility set to "private". This is not an issue when you are using Kargo, as you saw in the [Adding Repository Secret](#31-adding-repository-secret) section. Setting up Kubernetes to deploy workloads from a private image is [a little more complex](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) and setting up Kuberentes to pull from a registry with private images is beyond the scope of this tutorial. Therefore, you will have to make this image public for the rest of this quickstart. 1. Navigate to your package setting for the image by going to `https://github.com/users/${GITHUB_USER}/packages/container/package/guestbook` 2. Scroll down and click on `Change visiblility`. 3. Click on `Public`. 4. Type the name of the image, `guestbook`, to confirm. 5. Click on `I understand the consequences, change package visibility`. 6. Your image is now public. ### 4.2. Creating an Argo CD Instance Creating and configuring an Argo CD instance on the Akuity Platform is beyond the scope of this tutorial. So a script has been provided to expedite the process. You will need to create an Akuity Platform token before you run the script. :::tip If you are interested in learning more about managing Argo CD with the Akuity Platform, we recommend going through the [Introduction to Argo CD](https://docs.akuity.io/tutorials/intro-to-argo-cd) and [Advanced GitOps Workshop](https://docs.akuity.io/tutorials/adv-gitops) tutorials. ::: 1. On the Akuity Platform, navigate to Organization → API Keys → + New Key 2. Enter a description for your key. 3. Set the expiration to `7d` for 7 days. 4. Click on 🔑Owner 5. Click on Create 6. Make a note of the `AKUITY_API_KEY_ID` and `AKUITY_API_KEY_SECRET` and click Done 7. Navigate to your codespace and run `export AKUITY_API_KEY_ID=` and `export AKUITY_API_KEY_SECRET=` 8. Run `bash scripts/setup-argocd-instance.sh`. The script can take up to two minutes to run. 9. Once the script is done, go back to the Akuity Platform, and navigate to Argo CD → on the newly created Argo CD instance. 10. Enter `admin` as the username and `akuity-argocd` as the password and then click SIGN IN. 11. Note that Applications were created as part of the script. ### 4.3. Kargo Integration Integrating Kargo and Argo CD together is easy with the Akuity Platform. The integration is a two-step process first consisting of a change on the Akuity platform and the other a change being a manifest update. #### 4.3.1. Kargo Agent Setup In a previous section, [you set up a Kargo Agent](#24-connect-a-kargo-agent). In order to connect an Argo CD instance, an agent needs to be created for it. 1. On the Akuity Platform, click on Kargo 2. Select your Kargo instance. 3. Click on Agents 4. Click on + Register an agent 5. Name your agent (for example: *my-argocd-agent*). 6. Click on the Akuity Managed Argo CD dropdown. 7. Select the Argo CD instance that was created. 8. Enable Set as Default Shard 9. Click on Connect. The agents will go from "Progressing" to "Healthy". 10. (Optionally) You can safely delete the other agent if you like. #### 4.3.2. Update Kargo Stages The next step is to update all the `Stage`s to their corresponding Argo CD Applications. To do this you will have to add `appName: ` under `spec.promotionMechanisms.argoCDAppUpdates`. In this scenario, we will be setting up a 1:1 configuration between Kargo Stages and Argo CD Applications. However, you can have a Kargo Stage manage multiple Argo CD Applications. ```yaml spec: promotionMechanisms: argoCDAppUpdates: - appName: myappname ``` :::note For more information on Kargo Stage/Argo CD App configuration, see [the offical CRD docs](https://doc.crds.dev/github.com/akuity/kargo/kargo.akuity.io/Stage/v1alpha1#spec-promotionMechanisms-argoCDAppUpdates-appName). ::: To update the Kargo Stages, we will be using a script to expedite the process. Feel free to look at the script, it is a simple patch of the manifests. 1. Navigate to the Codespace. 2. Run `bash scripts/kargo-argocd-manifestupdate.sh` to update the manifests. 3. Navigate back to the Kargo UI 4. Select a stage, for example the dev 5. In the overview page, note that the Argo CD Application has been linked. 6. (Optionally) Check the other stages and their linked Argo CD Applications. ### 4.3. Promoting with Kargo Now that Kargo and Argo CD are integrated, Kargo can promote a change by not only writing back to Git; but also trigger and Argo CD Application Sync. 1. Navigate to your Codespace and simulate a release by creating a new build. ``` docker buildx imagetools create ghcr.io/akuity/guestbook:latest -t ghcr.io/${GITHUB_USER}/guestbook:v0.0.3 ``` 2. Back on the Kargo UI, click on the `Refresh` button on the `Warehouse` to tell kargo to fetch more freight. 3. Click on the icon on to initiate promotion. 4. Select the new `Freight` to promote. 5. Click on "YES" to confirm the promotion. 6. Navigate to the Argo CD UI and note that Kargo has triggered a sync once it promoted the `Freight`. 7. Back in the Kargo UI, the Kargo `Stage` now reflects the status of the artifacts of the `Freight` and where they are running. Feel free to explore promoting all the way down the pipeline, rollback, create new `Freight`, and add more Argo CD Applications for Kargo to manage their promotion. ## 5. Summary You have reached the end of the quickstart. You now have a Kargo instance managaing image promotions with integration with an Argo CD instance managing the deployment of those promotions. This is just the beginning and by now you might be able to see more complex deployment processes being managed easily with Kargo. --- ## Akuity Platform Tutorials --- ## FAQ ## General ### Can I purchase via AWS, GCP, or Microsoft/Azure Marketplace? Yes ### Does Akuity deploy to / work with multiple cloud providers? Yes, it works across multiple cloud providers, and it will also work with on-prem installations as well. ## Akuity Intelligence ### What is an AI token? An AI token is a small chunk of text that models use to process and generate response. On average, 1,000 tokens equal about 750 words or ~4,000 characters ### When do my AI Tokens reset? The AI tokens reset at the start of each month. ### What’s a runbook? Runbooks, at a high level, are the instruction sets that the On-Call Agent uses when responding to an active incident or scenario. These runbooks are written and stored in markdown formatting making them easy to read between both humans and Intelligence. --- ## Akuity Platform Troubleshooting ## Argo CD instance is in `Progressing` state The `Progressing` state indicates the instance is being reconfigured or updated. It usually goes away in several minutes. ## Can't log in to Argo CD ### Error: `Login is disabled` This is the default behavior for every new Argo CD instance. To enable login for the `admin` user, follow [these instructions](03-argocd/01-getting-started/30-enable-admin-user.mdx). ## Can't create an application ### Error: `no clusters connected` Check connection to the cluster: **Dashboard** 1. Navigate to Argo CD → _your instance_ → Clusters. 1. Find your cluster in the list and check the agent's health icon and version. :::note The agent's health might take several seconds to update. ::: **CLI** * TBD **API** * TBD - If agent health is `Unknown`, make sure that agent manifests are installed in your cluster and agent pods can connect to [akuity.cloud](https://akuity.cloud/) - You could also check agent logs in the managed cluster using a tool like [stern](https://github.com/stern/stern): - `stern akuity-agent -n akuity` - `stern argocd-repo-server -n akuity` ## Getting started with Troubleshoot.sh To expedite and troubleshoot any issue you mave have, we have created a support-bundle to collect basic cluster information, logs, and configmaps in the `akuity` namespace. Please feel free to verify or edit any information. :::note All information is collected locally and will be placed into the `support-bundle-*.tar.gz` file. ::: 1. Install [Krew](https://krew.sigs.k8s.io/docs/user-guide/setup/install/) or manually Homebrew: ```shell brew install krew ``` :::note Make sure to add the `${HOME}/.krew/bin` directory to you PATH environment variable. ```shell export PATH="${PATH}:${HOME}/.krew/bin" ``` ::: 2. Install the `support-bundle` by running the following command: ```shell kubectl krew install support-bundle ``` 3. Run the following command to scan your cluster: ```shell kubectl support-bundle https://dl.akuity.io/support-bundle/spec.yaml ``` 4. Attach the `support-bundle-*.tar.gz` file to your support ticket ## Self-Hosted Akuity Platform 1. Install the support-bundle as describe in the above section, then run the following command: ```shell kubectl support-bundle https://dl.akuity.io/support-bundle/sh-spec.yaml ``` :::note The support bundle for self-hosted customers collects basic cluster information, including logs and ConfigMaps from the `akuity-platform` namespace, along with logs from all Argo CD control plane namespaces. No secret or sensitive data is collected. ::: --- ## Knowledge Base Explore expert-driven solutions, integrations, and insights shared by the Akuity Community. See our [Knowledge Base](https://support.akuity.io/kb) which provides helpful articles and best practices for Akuity Platform users, covering several categories including **Argo CD**, **Akuity Platform**, and **Kargo** based on real-world customer experiences. --- ## Troubleshooting