For the complete documentation index, see llms.txt. This page is also available as Markdown.

Installing Argo CD

Install the P0 Argo CD integration: add the p0-connector account in Git, store its API token, deploy the connector, and add each Argo CD instance.

The Argo CD integration is in beta. Functionality and configuration may change.

You install Argo CD in two parts. An Argo CD connector is P0's connector, deployed in your AWS account or Google Cloud project. An Argo CD instance is one Argo CD that a connector reaches, with its own p0-connector account and API token. Install a connector once, then add each instance, either from the P0 app or with the P0 Terraform provider. For how the parts fit together, see How it works.

The shell commands on this page work as written in bash, zsh and fish. PowerShell and cmd quote differently.

Before you begin

Each Argo CD instance must:

  • Run Argo CD 3.0 or later.

  • Have its argocd-rbac-cm deployed by an Argo CD Application, from Git. P0 writes grants through that Application. An instance whose argocd-rbac-cm no Application deploys isn't supported.

  • Be served at the root of a public https address, such as https://argocd.example.com, with a certificate that's valid for its host and comes from a public certificate authority. The connector calls the instance over the internet. An Argo CD served under a path (server.rootpath) isn't supported.

  • Sign people in through SSO, with an identity provider that sends each person's email in lowercase. Argo CD matches the email exactly as the identity provider sends it, and P0 grants roles to the lowercase email.

You also need:

  • Write access to the Git repository that argocd-rbac-cm and argocd-cm are synced from.

  • An Argo CD admin with the argocd CLI, to create the p0-connector account's API token, and jq.

  • P0 installed in the cloud the connector runs in. P0 invokes the connector through its IAM management there, and the connector reads the API token from that cloud's secret manager:

The connector runs on
Install, for the connector's account or project
The secret is in
Install, for the secret's account or project

AWS Lambda

AWS Secrets Manager

The AWS Secrets Manager integration

Google Cloud Run

Google Secret Manager

The Google Secret Manager integration

  • Terraform, to deploy the connector:

    • AWS Lambda: Terraform 1.4 or later, run on Linux or macOS with Docker running and the AWS CLI signed in to the connector's account. Lambda runs images only from Amazon ECR, so the connector's Terraform copies P0's image from Docker Hub into an ECR repository with a shell script. The apply fails on Windows, and on remote runs that have no Docker, such as HCP Terraform's.

    • Google Cloud Run: Terraform 1.2 or later, and the hashicorp/google provider 6.0.0 or later. Cloud Run pulls P0's image from Docker Hub itself, so you don't need Docker. The machine that runs Terraform still has to reach Docker Hub, because every plan reads the image's digest there. The Service Usage API must be enabled in the connector's project, because the connector's Terraform enables the IAM and Cloud Run APIs through it.

    • Both: the kreuzwerker/docker provider 3.3.0 or later, below 5.0. The connector's Terraform declares it in a required_providers block of its own. If your configuration already has a required_providers block, add the docker entry to it, at 3.3 or later, and delete the generated block: Terraform refuses a second one.

The secret can be in a different account or project from the connector, in the same cloud. On AWS, the connector and the secret must both be in commercial regions, not in GovCloud, China, ISO or European Sovereign Cloud regions. For either one, the installer refuses another region with Argo CD supports only AWS commercial regions for now.

Step 1: Add the p0-connector account

The connector calls Argo CD as a local account named p0-connector. Add it in the Git repository that Argo CD's own configuration is synced from, then let Argo CD sync the change. You need two values:

  • The managing Application, as <project>/<application>: the Argo CD Application that deploys argocd-rbac-cm, and the project it's in. For example, default/argocd.

  • The namespace that argocd-rbac-cm is in. Usually argocd.

P0 shows these snippets with your values filled in on the instance's page, once you've entered them in Step 4: Add the Argo CD instance.

  1. Add the account to argocd-cm. The apiKey capability lets the account hold API tokens. Without login, it can't sign in to the UI or the CLI.

  1. Give the account its role in argocd-rbac-cm, and add email to scopes. Replace <project>/<application> with the managing Application and <namespace> with its namespace. Keep the scopes you already have, and add email to them. Add the lines to your own policy.csv, or to another policy key of yours.

  1. Merge the change, and let the managing Application sync it. To check that Argo CD knows the account, sign in with the argocd CLI and run argocd account get --account p0-connector. It shows Capabilities: apiKey.

Write scopes as a list on one line, in brackets, as above. scopes tells Argo CD which claims of a person's sign-in to match against policy lines, and P0's lines name people by email. Without email in it, no grant takes effect.

The account needs each line for one job:

Line
What the connector uses it for

applications, get on the managing Application

Read the Application, and read argocd-rbac-cm through it

applications, update//ConfigMap/<namespace>/argocd-rbac-cm on the managing Application

Write policy.p0.csv in argocd-rbac-cm through the Application, and update no other resource

projects, get, *

List your projects and the roles they define, so that people can request a project role

g, p0-connector, role:p0-connector

Give the account the role

Permissions not to grant the account

Don't grant the p0-connector account any of these. While it has one, P0 grants nothing on the instance, and adding the instance fails:

  • applications, sync, */*

  • applications, delete, */*

  • projects, update, *

  • accounts, update, *

  • clusters, update, *

Give the account only the four lines above. Don't make p0-connector an admin, don't give role:p0-connector a broader role through a g line, and don't set policy.default to a role that can do any of these.

Project roles

People can request any role that one of your AppProjects defines. P0 never creates or edits a project role, so define the roles you want people to request on each AppProject, under spec.roles, with the permissions a person needs:

P0 offers every role a project defines, including roles you made for CI tokens. To keep people from requesting those, deny them in an access policy with the project and role filters. See Access policies.

Step 2: Create and store the API token

The connector reads the p0-connector account's API token from your secret manager, as the JSON {"token": "<api token>"}. Create a token for each Argo CD instance, and store each in its own secret. You choose the secret's name, and you enter that name in P0 in Step 4: Add the Argo CD instance.

An Argo CD admin creates the token, because only an admin can create one for another account. Sign in to Argo CD with the argocd CLI as an admin, with argocd login <host> --sso or your usual sign-in. Then run the command for your secret manager. It creates a token that doesn't expire, and pipes it straight into the secret manager, so the token never shows on the screen, in a file or in your shell history.

For AWS Secrets Manager, with the AWS CLI signed in to the secret's account:

For Google Secret Manager, with gcloud signed in to an account that can create secrets in the project:

Nothing stops the secret manager command when argocd fails, so check that the secret holds a token. These print true, and never the token:

If the command fails after argocd ran, delete the token it created. Run argocd account get --account p0-connector to find the token's ID, then argocd account delete-token --account p0-connector <token-id>.

A secret's name follows its secret manager's rules:

Secret manager
Secret name

AWS Secrets Manager

Up to 512 letters, digits and /_+=.@-

Google Secret Manager

Up to 255 letters, digits, underscores and hyphens

For a secret in a different AWS account from the connector, the name can't end in a hyphen and six characters, such as -AbCdEf: Secrets Manager can't find a secret in another account by such a name, and P0 refuses it. Use another name, or a secret in the connector's own account.

On AWS, a secret in a different account from the connector must be encrypted with a customer-managed KMS key, and both the secret's resource policy and the key's policy must allow the connector's role. Add --kms-key-id <kms-key-arn> to create-secret. The instance's Terraform covers both policies, in Step 4: Add the Argo CD instance.

Step 3: Install the connector

One connector can serve several Argo CD instances, so skip this step if you already have a connector that should reach the new instance. Every instance behind a connector shares that connector's email domain pattern. See The email domain pattern.

  1. Open the P0 dashboard at p0.app and log in to your organization.

  2. In the sidebar, click Integrations. Under Resources, click Argo CD.

  3. Select the Argo CD connector component, and add a connector.

  4. Enter an ID for the connector, such as prod. Each Argo CD instance names its connector by this ID. Use lowercase letters, digits and hyphens, starting and ending with a letter or digit, up to 63 characters.

  5. Under Connector hosting, choose AWS Lambda or Google Cloud Run, and fill in the fields:

Hosting
Field
What to enter

AWS Lambda

AWS account ID

The account the connector runs in. The list shows the accounts where P0's AWS IAM management is installed.

AWS Lambda

Connector name

The Lambda function's name, which is also the name of the IAM role it runs as. Use 2 to 64 characters: lowercase letters, digits and single hyphens, starting with a letter and ending with a letter or digit.

AWS Lambda

Connector region

An AWS region, such as us-west-2

Google Cloud Run

GCP project ID

The project the connector runs in. The list shows the projects where P0's Google Cloud IAM management is installed.

Google Cloud Run

Connector name

The Cloud Run service's name, which is also the ID of the service account it runs as. Use 6 to 30 characters: lowercase letters, digits and hyphens, starting with a letter and ending with a letter or digit.

Google Cloud Run

Connector region

A Google Cloud region, such as us-west1

  1. Continue to the connector's Terraform. P0 fills it in with the values you entered.

  2. Add the Terraform to your configuration, set the email domain pattern variable it declares, and apply it. See The email domain pattern.

  3. Continue in the installer. P0 checks that it can invoke the connector. IAM changes can take a few seconds to take effect, so if P0 is denied access right after you apply, wait and try again.

Keep your copy of the connector's Terraform. You change the email domain pattern and the connector's image in it later.

Don't raise the connector's timeout. The Terraform sets 60 seconds for the Lambda function and 300 seconds for the Cloud Run service.

The email domain pattern

The connector gives Argo CD access only to people whose email domain matches a regular expression that you set. The connector's Terraform declares it as a required variable, and sets it on the connector as the ALLOWED_EMAIL_DOMAIN_PATTERN environment variable. P0 never stores or sends the pattern, and can't change it.

The variable's name ends in _allowed_email_domain_pattern and carries the connector's ID, with each hyphen written as an underscore. For the connector prod-eu it's p0_argocd_connector_prod_eu_allowed_email_domain_pattern. Copy the name from the Terraform that P0 generated.

Write the pattern this way:

  • Match the whole domain. The connector tests the pattern against the text after the @, and the pattern has to match all of it. Leave out the @, and leave out ^ and $: the connector anchors the pattern itself.

  • Write each dot as [.]. A bare . matches any character, so example.com also allows exampleXcom. Write example[.]com.

  • Separate several domains with |, as in example[.]com|example[.]net.

  • Name subdomains if you want them. example[.]com doesn't match mail.example.com. To allow every subdomain too, use ([a-z0-9-]+[.])*example[.]com.

Capitalization doesn't matter.

Set the variable in a .tfvars file:

To pass it on the command line instead, single-quote it so the shell leaves the brackets alone:

While the pattern is unset, blank, or isn't a regular expression that compiles, the connector refuses every request, and P0 can't finish installing an instance through it.

To change the pattern later, change the variable and apply again. The connector uses the new pattern from its next call, and nothing changes in P0. A person whose domain the new pattern no longer allows keeps the access they already have until it ends, and P0 still revokes it then.

Step 4: Add the Argo CD instance

  1. On the Argo CD integration's page in P0, select the Argo CD instance component, and add an instance.

  2. Enter an ID for the instance, such as prod. People name the instance by this ID when they request access, and access policies match it. It follows the same rule as a connector's ID.

  3. Fill in the fields:

Field
What to enter

Connector

The connector that reaches this instance. The list shows the connectors you've finished installing.

Argo CD URL

The instance's address, as https://<host> or https://<host>:<port>, such as https://argocd.example.com. Write it in lowercase, with nothing after the host or port: no trailing slash, no path, no username or password, and no :443.

Managing application

The Application that deploys argocd-rbac-cm, as <project>/<application>, such as default/argocd. The same value as in the account's policy lines in Step 1: Add the p0-connector account.

Namespace

The namespace argocd-rbac-cm is in. Leave it empty for argocd.

Secret manager provider

AWS Secrets Manager for a connector on AWS Lambda, or Google Secret Manager for one on Google Cloud Run

Installation, under Secret manager provider

The account or project the secret is in. The list shows the ones where P0's integration for that secret manager is installed.

Secrets region, for AWS Secrets Manager

The secret's region, such as us-west-2

API token secret

The name of the secret from Step 2: Create and store the API token. Enter the name, never an ARN or a resource name, and never the token itself.

  1. Continue. If you haven't made the Git change in Step 1: Add the p0-connector account or stored the token in Step 2: Create and store the API token yet, the instance's page shows both, with this instance's values filled in.

  2. Apply the instance's Terraform, after the connector's. It gives the connector read access to this instance's secret, and to no other secret. On AWS, if a customer-managed KMS key encrypts the secret, set kms_key_arn in the Terraform to the key's ARN, not an alias, before you apply.

    For a secret on AWS in a different account from the connector, P0 gives you three pieces, in order:

    1. Terraform for the connector's account: read access on the connector's role. The plan fails until you set kms_key_arn.

    2. Terraform for the secret's account: the secret's resource policy, letting the connector's role read the secret. Apply it with credentials for the secret's account. It replaces any resource policy the secret already has. If the secret has one, add the statement to that policy instead of applying this. To check, run aws secretsmanager get-resource-policy --secret-id <secret-name> --region <region> in the secret's account.

    3. A statement for the KMS key's policy, as JSON. Add it to the policy of the key that encrypts the secret, beside the statements already there. Don't replace the key's policy with it.

    If the connector's role is ever deleted and created again, apply the second piece again and add the key statement again: AWS's policies name the old role, not the new one.

  3. Continue in the installer. P0 checks the instance through the connector, as in What the install checks. Once every check passes, the instance's page shows the Argo CD version and the connector's email domain pattern.

The connector needs these permissions on each instance's secret, which the instance's Terraform grants:

Secret manager
What the connector's identity needs

AWS Secrets Manager

secretsmanager:GetSecretValue on the secret, and kms:Decrypt on its key if a customer-managed KMS key encrypts it

Google Secret Manager

roles/secretmanager.secretAccessor and roles/secretmanager.viewer, both on the secret

What the install checks

P0 checks the instance through the connector, in this order, and stops at the first check that fails. The message starts The Argo CD instance <instance> failed its install check while, names the check, and says what to fix.

#
The check
If it fails

1

The connector's email domain pattern is set, and compiles

Set the variable in the connector's Terraform, as in The email domain pattern, and apply it.

2

The connector can read the secret, and it holds {"token": "<api token>"}

Check the secret's name, account or project, and region, the instance's Terraform, and what the secret holds. A secret that doesn't exist can be refused the same way as one the connector can't read.

3

The address answers as Argo CD does

Check the URL, that its host resolves from the connector, and that its certificate is valid and from a public certificate authority. A 401 or 403 here comes from a proxy or gateway in front of Argo CD: let the connector through.

4

Argo CD is version 3.0 or later

Upgrade Argo CD.

5

Argo CD accepts the token, and it's the p0-connector account's

Store a token of the p0-connector account, as in Step 2: Create and store the API token. A token of another account, or one Argo CD treats as an anonymous caller, fails here.

6

The account can read the managing Application, and it's in the project you entered

Check the policy lines from Step 1: Add the p0-connector account, and the managing Application's name and project. Argo CD answers the same way for an Application that doesn't exist and one the account can't read.

7

The managing Application deploys argocd-rbac-cm, in the namespace you entered

Check the namespace. If no Application deploys argocd-rbac-cm, the instance isn't supported.

8

scopes in argocd-rbac-cm includes email

Add email to scopes, written as a list on one line, such as "[groups, email]".

9

policy.p0.csv is absent, or holds only lines P0 writes

Move each other line to another policy key, or remove it. The message names the lines by number.

10

Argo CD accepts every line of every policy key

Fix or remove the line the message names by key and line number. While one line doesn't parse, Argo CD ignores every change to the policy, P0's included.

11

The account can list projects

Add the projects, get, * line from Step 1: Add the p0-connector account.

12

The account has none of the Permissions not to grant the account

Take away what the message names.

13

The account can update argocd-rbac-cm through the managing Application

Check the applications, update//ConfigMap/... line from Step 1: Add the p0-connector account, and that its namespace and Application match.

The last check sends Argo CD an empty change to argocd-rbac-cm. It changes nothing, and shows in Argo CD's audit log.

If the fix is in Argo CD, in Git, in the secret's contents, in the connector's read access or in the email domain pattern, make it and try again. If the fix is a value you entered for the instance, delete the instance and add it again with the right value.

Install with Terraform

The p0_argocd_* resources require P0 Terraform provider v0.70.0 or later.

Instead of the installer, you can install Argo CD with the P0 Terraform provider. See Manage integrations as code with the P0 Terraform provider. You still add the p0-connector account and store its API token, as in Step 1: Add the p0-connector account and Step 2: Create and store the API token. Each resource's page in the Terraform registry has a complete example for each cloud, including the cloud resources. Create the resources in this order:

  1. Stage the connector with p0_argocd_connector_staged. Set id and hosting. For Google Cloud Run, P0 answers with hosting.connector_service_account, the service account the connector must run as.

  2. Deploy the connector where hosting says, and set its ALLOWED_EMAIL_DOMAIN_PATTERN environment variable. The pattern isn't an attribute of any P0 resource. Write it as described in The email domain pattern, such as "example[.]com". Pin the connector's image to a published tag and that tag's digest, as the examples do. P0 publishes the tags on Docker Hub.

    • AWS Lambda: use the image p0security/p0-connector-argocd, copied into Amazon ECR. Name the function's role after the connector, and give P0's AWS IAM management role lambda:InvokeFunction on the function.

    • Google Cloud Run: use the image p0security/p0-connector-argocd-gcloud, running as hosting.connector_service_account. Give P0's Google Cloud service account roles/run.invoker and roles/run.viewer on the service, and set the connector's INVOKER_SA_EMAIL environment variable to that same service account's email. The connector refuses every call while INVOKER_SA_EMAIL is unset.

  3. Install the connector with p0_argocd_connector, with the same id and hosting as the staged resource. P0 checks that it can invoke the connector.

  4. Give the connector read access to the secret, with the permissions in Step 4: Add the Argo CD instance.

  5. Add each instance with p0_argocd_instance. Set id, connector, url, managing_app, vault and secret_name, and namespace if argocd-rbac-cm isn't in argocd. Make it depend on the secret's read access.

For example, an instance on a connector that runs on Google Cloud Run:

Creating the instance has P0 check it through the connector, as in What the install checks. If a check fails, the apply fails with P0's message. Fix what the message names and apply again.

A plan refuses a change to an installed instance's url, managing_app or namespace. Changing its id, connector, vault or secret_name replaces the instance, and changing a connector's id or hosting replaces the connector. Read Remove or replace an instance before you apply a replacement.

Import what you added in the P0 app

If you already added a connector or an instance in the P0 app, the apply fails and says to import it. Import a connector into both of its resources, and an instance into its one:

Change the install later

Rotate the API token

The old token keeps working until you delete it, so you can rotate without an outage:

  1. Create a new token and store it in the same secret as a new version.

For AWS Secrets Manager:

For Google Secret Manager:

  1. Check that the new version holds a token, with the same command as in Step 2: Create and store the API token.

  2. Delete the old token. Run argocd account get --account p0-connector to list the account's tokens, with the ID and issue time of each, then delete the old one by its ID:

The connector reads the secret on every call, so it uses the new token from its next call. Nothing changes in P0 or in the connector's Terraform.

Update the connector

To move the connector to a new image, change the image's pin in your copy of the connector's Terraform and apply it again. On both clouds the pin is image_tag and image_digest, in the Terraform's locals. Nothing changes in P0.

  • AWS Lambda: Terraform copies the new image into your ECR repository and redeploys the function, so run it where Docker is running, as for the first apply. To find a tag's digest, run docker buildx imagetools inspect p0security/p0-connector-argocd:<tag> and copy the Digest it prints.

  • Google Cloud Run: Terraform redeploys the Cloud Run service with the new image, which Cloud Run pulls from Docker Hub. You don't need Docker. Pin the tag's own digest: the multi-platform index digest, not the digest of one platform's image, which Docker Hub also lists on the tag's page. The plan compares the pin with the tag's index digest, so a per-platform digest stops it. If you have Docker, docker buildx imagetools inspect p0security/p0-connector-argocd-gcloud:<tag> prints the index digest as Digest.

If the plan stops with The connector image's tag doesn't resolve to the digest pinned here, the tag on Docker Hub and the digest you pinned are different images. Terraform changes nothing: edit the pin so the tag and its digest match, and apply again.

Remove a connector

Remove each Argo CD instance that uses the connector first, as in Remove or replace an instance, and destroy each instance's Terraform, which removes its read grant. Then destroy the connector's Terraform, and delete the connector in P0.

With the Terraform provider, P0 refuses to destroy a p0_argocd_connector while an instance uses it.

  • AWS Lambda: each instance's grant is a policy on the connector's role, and Terraform doesn't delete a role that still has one, so destroying the connector's Terraform first fails.

  • Google Cloud Run: destroying the connector deletes its service account. A read grant left behind on a secret names an account that no longer exists: remove it with that instance's Terraform, or from the secret's permissions.

Remove or replace an instance

Before you remove or replace an instance, let its open requests end, or revoke them. Check for open requests on the Activity tab of Access Management.

  • To change the connector, the secret manager or the secret's name, delete the instance and add it again under the same ID. With Terraform, changing connector, vault or secret_name does the same. A revoke that comes due while the instance isn't installed fails, and needs Retry revoke once the instance is installed again.

  • To move to another address, managing Application or namespace, add a new instance with its own ID, and remove the old one once its open requests have ended. The new ID is what people pass as --instance, and what the instance filter in your access policies matches, so update both.

  • If you remove an instance for good while requests are open, those requests show as errored when they end, with a message that starts P0 is not installed for the instance and names the instance. Remove those people's lines from policy.p0.csv by hand.

To remove the integration from an instance entirely, after you remove it from P0:

  1. Delete the account's API tokens, with argocd account delete-token --account p0-connector <token-id> for each.

  2. Remove the p0-connector lines from argocd-cm and argocd-rbac-cm in Git, and let Argo CD sync.

  3. If argocd-rbac-cm still has a policy.p0.csv key, each line in it is a grant P0 can no longer revoke. Remove the key from the live ConfigMap.

  4. Delete the API token's secret.

Last updated