> For the complete documentation index, see [llms.txt](https://docs.p0.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.p0.dev/integrations/resource-integrations/argocd/installation.md).

# 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.

{% hint style="info" %}
The Argo CD integration is in beta. Functionality and configuration may change.
{% endhint %}

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 [Argo CD](https://docs.p0.dev/integrations/resource-integrations/argocd.md#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](https://argo-cd.readthedocs.io/en/stable/cli_installation/), to create the `p0-connector` account's API token, and [`jq`](https://jqlang.org/download/).
* **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](https://docs.p0.dev/integrations/resource-integrations/aws.md#setting-up-aws-iam-management)                            | AWS Secrets Manager   | The [AWS Secrets Manager](https://docs.p0.dev/integrations/resource-integrations/aws-secrets-manager.md) integration     |
| Google Cloud Run      | [Google Cloud](https://docs.p0.dev/integrations/resource-integrations/google-cloud.md#install-iam-management-on-each-project) | Google Secret Manager | The [Google Secret Manager](https://docs.p0.dev/integrations/resource-integrations/google-secret-manager.md) integration |

* [**Terraform**](https://developer.hashicorp.com/terraform/install), 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](https://console.cloud.google.com/apis/library/serviceusage.googleapis.com) 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](#step-4-add-the-argo-cd-instance "mention").

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.

```yaml
# argocd-cm
data:
  accounts.p0-connector: apiKey
```

2. **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.

```yaml
# argocd-rbac-cm
data:
  scopes: "[groups, email]"
  policy.csv: |
    p, role:p0-connector, applications, get, <project>/<application>, allow
    p, role:p0-connector, applications, update//ConfigMap/<namespace>/argocd-rbac-cm, <project>/<application>, allow
    p, role:p0-connector, projects, get, *, allow
    g, p0-connector, role:p0-connector
```

3. **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                                                                       |

{% hint style="warning" %}
**Never add the `policy.p0.csv` key to Git, and never sync `argocd-rbac-cm` with `Replace=true`.** P0 writes every grant to `policy.p0.csv`. If Git declares the key, the next sync replaces P0's lines with what Git holds. A replace sync deletes every key that Git doesn't declare. Either way, everyone loses the access P0 granted at once. P0 doesn't put the lines back: people request access again.
{% endhint %}

### 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:

```yaml
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: payments
  namespace: argocd
spec:
  roles:
    - name: deployer
      description: Sync the payments Applications
      policies:
        - p, proj:payments:deployer, applications, get, payments/*, allow
        - p, proj:payments:deployer, applications, sync, payments/*, allow
```

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 [Argo CD](https://docs.p0.dev/integrations/resource-integrations/argocd.md#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](#step-4-add-the-argo-cd-instance "mention").

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:

```bash
argocd account generate-token --account p0-connector \
  | jq -Rc '{token: .}' \
  | aws secretsmanager create-secret --name <secret-name> --region <region> --secret-string file:///dev/stdin
```

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

```bash
argocd account generate-token --account p0-connector \
  | jq -Rc '{token: .}' \
  | gcloud secrets create <secret-name> --project <project-id> --data-file=-
```

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

```bash
aws secretsmanager get-secret-value --secret-id <secret-name> --region <region> \
  --query SecretString --output text | jq -e '.token | length > 0'
```

```bash
gcloud secrets versions access latest --secret <secret-name> --project <project-id> \
  | jq -e '.token | length > 0'
```

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-4-add-the-argo-cd-instance "mention").

{% hint style="warning" %}
**The token can change `argocd-rbac-cm`, the ConfigMap that holds your whole Argo CD policy.** Keep it only in your secret manager, readable only by the connector. If it's ever exposed, replace it as in [#rotate-the-api-token](#rotate-the-api-token "mention").
{% endhint %}

## 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](#the-email-domain-pattern "mention").

{% hint style="warning" %}
**A connector's ID and where it runs can't change once you add it.** To move a connector, add a new one.
{% endhint %}

1. Open the P0 dashboard at [p0.app](https://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`                                                                                                                                                                      |

6. Continue to the connector's Terraform. P0 fills it in with the values you entered.
7. Add the Terraform to your configuration, set the email domain pattern variable it declares, and apply it. See [#the-email-domain-pattern](#the-email-domain-pattern "mention").
8. 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.

{% hint style="warning" %}
**Don't destroy and recreate the connector's service account.** Google Cloud treats a recreated service account as a new identity, even with the same email, so it loses the read access that each Argo CD instance granted it. If you recreate it, apply each instance's Terraform again, and deploy the connector again.
{% endhint %}

### 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:

```terraform
p0_argocd_connector_prod_eu_allowed_email_domain_pattern = "example[.]com"
```

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

```bash
terraform apply -var 'p0_argocd_connector_prod_eu_allowed_email_domain_pattern=example[.]com'
```

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

{% hint style="warning" %}
**None of an instance's settings can change once you add it, so check each one before you continue.** To use another connector, secret manager or secret name, you delete the instance and add it again. For another address, managing Application or namespace, you add a new instance with its own ID. Read [#remove-or-replace-an-instance](#remove-or-replace-an-instance "mention") first.
{% endhint %}

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](#step-1-add-the-p0-connector-account "mention"). |
| **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](#step-2-create-and-store-the-api-token "mention"). Enter the name, never an ARN or a resource name, and never the token itself.                                              |

4. Continue. If you haven't made the Git change in [#step-1-add-the-p0-connector-account](#step-1-add-the-p0-connector-account "mention") or stored the token in [#step-2-create-and-store-the-api-token](#step-2-create-and-store-the-api-token "mention") yet, the instance's page shows both, with this instance's values filled in.
5. 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.
6. Continue in the installer. P0 checks the instance through the connector, as in [#what-the-install-checks](#what-the-install-checks "mention"). Once every check passes, the instance's page shows the Argo CD version and the connector's email domain pattern.

{% hint style="warning" %}
**Keep the connector's read access to the API token secrets of its own instances, and to nothing else.** P0 names the secret in each call to the connector, so any other secret the connector can read, whether through a wildcard or through a grant on the whole account or project, is one a call could point it at.
{% endhint %}

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                             |

{% hint style="success" %}
People can now request Argo CD roles on the instance. See [Requesting Argo CD access](https://docs.p0.dev/integrations/resource-integrations/argocd/requesting-access.md).
{% endhint %}

### 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](#the-email-domain-pattern "mention"), 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](#step-2-create-and-store-the-api-token "mention"). 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](#step-1-add-the-p0-connector-account "mention"), 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](#step-1-add-the-p0-connector-account "mention").                                                                                                                                            |
| 12 | The account has none of the [#permissions-not-to-grant-the-account](#permissions-not-to-grant-the-account "mention") | 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](#step-1-add-the-p0-connector-account "mention"), 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

{% hint style="info" %}
The `p0_argocd_*` resources require P0 Terraform provider [v0.70.0](https://github.com/p0-security/terraform-provider-p0/releases/tag/v0.70.0) or later.
{% endhint %}

Instead of the installer, you can install Argo CD with the P0 Terraform provider. See [Manage integrations as code with the P0 Terraform provider](https://docs.p0.dev/getting-started/get-started-with-the-p0-terraform-provider.md). You still add the `p0-connector` account and store its API token, as in [#step-1-add-the-p0-connector-account](#step-1-add-the-p0-connector-account "mention") and [#step-2-create-and-store-the-api-token](#step-2-create-and-store-the-api-token "mention"). 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`](https://registry.terraform.io/providers/p0-security/p0/latest/docs/resources/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](#the-email-domain-pattern "mention"), 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`](https://registry.terraform.io/providers/p0-security/p0/latest/docs/resources/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](#step-4-add-the-argo-cd-instance "mention").
5. **Add each instance** with [`p0_argocd_instance`](https://registry.terraform.io/providers/p0-security/p0/latest/docs/resources/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:

```terraform
resource "p0_argocd_instance" "prod" {
  id           = "prod"
  connector    = p0_argocd_connector.prod.id
  url          = "https://argocd.example.com"
  managing_app = "default/argocd"

  vault = {
    type       = "gcp-sm"
    project_id = "my-secrets-project"
  }
  secret_name = "argocd-prod-token"

  depends_on = [
    google_secret_manager_secret_iam_member.argocd_accessor,
    google_secret_manager_secret_iam_member.argocd_viewer,
  ]
}
```

Creating the instance has P0 check it through the connector, as in [#what-the-install-checks](#what-the-install-checks "mention"). 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](#remove-or-replace-an-instance "mention") 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:

```bash
terraform import p0_argocd_connector_staged.prod prod
terraform import p0_argocd_connector.prod prod
terraform import p0_argocd_instance.prod prod
```

## 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:

```bash
argocd account generate-token --account p0-connector \
  | jq -Rc '{token: .}' \
  | aws secretsmanager put-secret-value --secret-id <secret-name> --region <region> --secret-string file:///dev/stdin
```

For Google Secret Manager:

```bash
argocd account generate-token --account p0-connector \
  | jq -Rc '{token: .}' \
  | gcloud secrets versions add <secret-name> --project <project-id> --data-file=-
```

2. Check that the new version holds a token, with the same command as in [#step-2-create-and-store-the-api-token](#step-2-create-and-store-the-api-token "mention").
3. 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:

```bash
argocd account delete-token --account p0-connector <old-token-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](#remove-or-replace-an-instance "mention"), 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

{% hint style="warning" %}
**Removing an instance from P0 doesn't revoke the access P0 granted on it.** The lines P0 wrote stay in `policy.p0.csv`, and P0 can't remove them while the instance isn't installed.
{% endhint %}

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](https://docs.p0.dev/access-management/access-management.md).

* **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.
