Skip to main content
Sponsor @cloudposse

Setup Argo CD

This setup guide will walk you through the process of setting up ArgoCD in your environment.

StepsExample
1. Vendor ArgoCD componentsatmos workflow vendor -f argocd
2. Create ArgoCD reposClickOps
3. Create GitHub PATsArgoCD Integrations: How to set up Authorization for ArgoCD with GitHub PATs
4. Deploy ArgoCD repo configurationatmos workflow deploy/argocd-repos -f argocd
5. Create IAM Identity Center AppsArgoCD Integrations: How to create an AWS Identity Center Application
6. Deploy ArgoCDatmos workflow deploy/argocd -f argocd
7. Create example-appClickOps

Requirements​

In order to deploy ArgoCD, EKS must be fully deployed and functional. In particular, the user deploying the cluster must have a working VPN connection to the targeted account. See the EKS documentation for details.

All deployment steps below assume that the environment has been successfully set up with the following steps.

  1. Sign into AWS via Leapp
  2. Connect to the VPN
  3. Open Geodesic

Steps

2 Vendor Components​

First vendor all related components for the ArgoCD layer:

These are the commands included in the vendor workflow in the examples/snippets/stacks/workflows/argocd.yaml file:
    No commands found
Too many commands? Consider using the Atmos workflow! 🚀

3 Establish a Bot User​

We deploy a number of GitHub Personal Access Tokens (PATs) as part of the EKS with ArgoCD application. By default each PAT is given the least-access required for the given job.

Each one of these PATs will be associated with a given user. We recommend creating or using an existing "bot" user. For example, at Cloud Posse we have the "cloudpossebot" GitHub user. This user has its own email address and GitHub account, is accessible from our internal 1Password vault for all privileged users, and has all access keys and tokens stored with it in 1Password.

This bot user will need permission to manage a few repositories in your Organization. If you wish to simplify deployment, you can grant this user permission to create repositories. See (Create Permission for the Bot User)[#Create Permission for the Bot User].

Use this bot user for all access tokens in the remainder of this guide.

4 Create ArgoCD GitHub Repositories​

5 Create all ArgoCD PATs​

We will need several PATs for the following steps. Now that the ArgoCD repos are created, you can create all required PATs.

Please see ArgoCD Integrations: How to set up Authorization for ArgoCD with GitHub PATs and follow all steps.

6 Deploy ArgoCD GitHub Repositories Configuration​

Deploy the ArgoCD configuration for the two GitHub repos with the following workflow:

These are the commands included in the deploy/argocd-repos workflow in the examples/snippets/stacks/workflows/argocd.yaml file:
    No commands found
Too many commands? Consider using the Atmos workflow! 🚀

Once this finishes, review the two repos in your GitHub Organization. These should both be fully configured at this point.

Now that the ArgoCD deployment repos are configured, we need to create GitHub PATs for ArgoCD.

7 Create AWS Identity Center Applications​

In order to authenticate with ArgoCD, we recommend using an AWS IAM Identity Center SAML Application. These apps can use existing Identity Center groups that we've already setup as part of the Identity layer.

Please see ArgoCD Integrations: How to create an AWS Identity Center Application and follow all steps.

8 Deploy ArgoCD to each EKS Cluster​

Once the GitHub repositories are in place and the SAML applications have been created and configuration uploaded to SSM, we're ready to deploy ArgoCD to each cluster.

Deploy eks/argocd to each cluster with the following workflow:

These are the commands included in the deploy/argocd workflow in the examples/snippets/stacks/workflows/argocd.yaml file:
    No commands found
Too many commands? Consider using the Atmos workflow! 🚀

9 Validation​

Once all deployment steps are completed, ArgoCD should be accessible at the following URLs. Please note that you must be able to authenticate with AWS Identity Center to access any given app.

Next Steps​

Assuming login goes well, here's a checklist of GitHub repos needed to connect ArgoCD:

  • acme/infra-acme repo (Should already exist!)
    • acme/infra-acme/.github/environments private workflows. This directory stores private environment configurations. Primarily, that is the cloudposse/github-action-yaml-config-query action used to get role, namespace, and cluster mapping for each environment.
  • (2) ArgoCD deploy nonprod and prod (Should already be created by argocd-repo component in earlier step)
    • argocd-deploy-non-prod
    • argocd-deploy-prod
  • acme/example-app repo should be private repo generated from the app-on-eks-with-argocd template
Sensitive Log Output

Note that all of these workflow runs run from within your private app repo, so any sensitive log output will not be public.

1 Environment Configuration​

Update the cloudposse/github-action-interface-environment action to point to your infrastructure repository.

  1. Set implementation_repository to acme/infra-acme
  2. Verify implementation_path, implementation_file, and implementation_ref match your local configuration.

Example app reference

2 Verify GitHub OIDC Access Roles​

Capitalization Matters!

The IDP permissions in IAM will be sensitive to capitalization, and yet the docker image must -not- have uppercase letters!

Make sure that your repo is allowed to assume roles for all relevant clusters and ECR repos:

  1. Update the github_actions_allowed_repos variable in ecr, eks/cluster, or any other relevant components with GitHub OIDC access.
  2. If your GitHub Organization has mixed capitalization cases, make sure these entries are case-sensitive

3 GitHub Environment Secrets​

Add each of the following secrets to the acme/example-app repo:

  1. github-private-actions-pat: ${{ secrets.PUBLIC_REPO_ACCESS_TOKEN }}
  2. registry: ${{ secrets.ECR_REGISTRY }}
  3. secret-outputs-passphrase: ${{ secrets.GHA_SECRET_OUTPUT_PASSPHRASE }}
  4. ecr-region: ${{ secrets.ECR_REGION }}
  5. ecr-iam-role: ${{ secrets.ECR_IAM_ROLE }}

4 Specify Ingress Group​

  1. Update the deploy/releases/app.yaml
  2. Make sure the ingress is not set to default. It should likely be alb-controller-ingress-group. you can read more about this from our docs on the alb controller component
  3. Set the domain accordingly. Each environment will need the service domain + environment.stage.tenant (ie. use2.staging.plat.acme-svc.com )
  4. If your organization has mixed case, you'll need to edit the organization parameter to be lowercased in the GitHub workflows: feature-branch.yml, main-branch.yaml, and release.yaml

FAQ​

Migrating from ArgoCD version <1.305.0 to 1.305.0​

In order to migrate to 1.305.0 from a lesser version, delete the previous SSM parameters in each account for /argocd/notifications/notifiers/service_webhook_github-commit-status/github-token and redeploy github-webhook-pat, eks/argocd, and argocd-repos.

Or use the following workflow:

These are the commands included in the migrate_less_1_305 workflow in the examples/snippets/stacks/workflows/argocd.yaml file:
    No commands found
Too many commands? Consider using the Atmos workflow! 🚀

About GitHub PATs​

We deploy a number of GitHub Personal Access Tokens (PAT). Each has a specific purpose and is limited to the fine-grained scope required by that specific job. These are as follows:

  1. Terraform argocd-repo Access​

    The first PAT we deploy is used by Terraform with the argocd-repo component. This PAT is used to create and manage the ArgoCD deployment repositories, add deployment ssh keys for those repos, and is stored in AWS SSM Parameter Store.

    Terraform will pull that PAT from SSM typically using the argocd/github path in the core-auto account.

  2. Terraform eks/argocd Access​

    The next two PATs are also used by Terraform now with the eks/argocd component. Each of these PATs is used to register the webhook in GitHub for the ArgoCD Application created with this given component.

    Terraform will pull that PAT from SSM typically using the argocd/github path in plat-dev, plat-staging, and plat-prod accounts. You may notice this is the same path as #1 above. These PATs can be combined into a single PAT, as both are only used by Terraform.

  3. ArgoCD GitHub Notification Access​

    The next PAT is used by the ArgoCD notifications system to set the GitHub to commit status on successful deployments. This PAT is stored in SSM and pulled by the eks/argocd component. That component will pass the token to the ArgoCD application in the given EKS cluster. That ArgoCD Application uses that PAT only when synchronous mode is enabled.

    We store this PAT in SSM using the argocd/notifications/notifiers/common/github-token path

  4. GitHub Release Workflow Access​

The final two PATs are used in the release engineering workflows; one for nonprod and one for prod. This token should allow write permissions in infra-acme and the given ArgoCD deploy repo.