AWS eks: Argo CD custom endpoint prefix documentation
Summary
Adds documentation for specifying a custom endpoint prefix for an EKS Argo CD capability, including hostname format, naming constraints, reserved prefixes, CLI/CloudFormation examples, and a security note not to include sensitive information in the prefix.
Security assessment
The changed line documents that the endpoint hostname is not secret, warns against putting sensitive information in a custom endpoint prefix, and reiterates that AWS Identity Center authentication and Argo CD RBAC control access. This is security best-practice guidance, not a fix for a specific vulnerability or incident.
Evidence
+The endpoint hostname is not a secret, and knowing it doesn’t grant access to your Argo CD instance. The default hostname exposes the same non-secret information that already appears in the capability Amazon Resource Name (ARN). The `create-capability`, `describe-capability`, and `list-capabilities` operations return this ARN. If you specify a custom endpoint prefix, the hostname also exposes the prefix that you chose. Don’t include sensitive information in an endpoint prefix. AWS Identity Center authentication and Argo CD role-based access control (RBAC) control access to the Argo CD UI and API.
Diff
diff --git a/eks/latest/userguide/working-with-argocd.md b/eks/latest/userguide/working-with-argocd.md index e469ba1..3af2856 100644 --- a//eks/latest/userguide/working-with-argocd.md +++ b//eks/latest/userguide/working-with-argocd.md @@ -67 +67 @@ The UI provides visual application topology, sync status and history, resource h -When you create an Argo CD capability, you receive a unique endpoint for both the Argo CD UI and API. The endpoint hostname is _deterministic_ : It uses values you already know, such as your capability name, cluster name, AWS account ID, and AWS Region. If you delete a capability and recreate it with the same cluster name and capability name, you get the same endpoint. Because the hostname is predictable, you can construct it in advance. For example, you can pre-configure DNS, automation, or Git webhook integrations before the capability finishes provisioning. For any capability, the `serverUrl` value from `describe-capability` is the definitive endpoint. +When you create an Argo CD capability, you receive a unique endpoint for both the Argo CD UI and API. By default, the endpoint hostname is _deterministic_ : It uses values you already know, such as your capability name, cluster name, AWS account ID, and AWS Region. If you delete a capability and recreate it with the same cluster name and capability name, you get the same default endpoint. Because the hostname is predictable, you can construct it in advance. For example, you can pre-configure DNS, automation, or Git webhook integrations before the capability finishes provisioning. You can also specify a custom prefix for the hostname. For more information, see Use a custom endpoint prefix. For any capability, the `serverUrl` value from `describe-capability` is the definitive endpoint. @@ -91 +91 @@ The `serverUrl` field and the endpoint’s DNS records are available after the c -The Argo CD endpoint uses the following format: +By default, the Argo CD endpoint uses the following format: @@ -133,0 +134,83 @@ Both commands return `dc855fdf`. +### Use a custom endpoint prefix + +Instead of using the default hostname, you can specify a prefix for your endpoint. If you specify an endpoint prefix when you create the capability, the endpoint uses the following format: + + + https://endpoint-prefix-account-id.eks-capabilities.region-code.amazonaws.com + +A custom prefix replaces the capability name and the hash, so the hostname starts with your prefix followed by your AWS account ID. For example, the prefix `payments` in account `111122223333` in the `us-west-2` Region produces the following endpoint: + + + https://payments-111122223333.eks-capabilities.us-west-2.amazonaws.com + +An endpoint prefix must meet the following requirements: + + * Contains 1 to 50 characters + + * Contains only lowercase letters (`a-z`), numbers (`0-9`), and hyphens (`-`) + + * Starts and ends with a letter or a number + + * Is unique within your AWS account and AWS Region + + * Isn’t a prefix that Amazon EKS reserves + + + + +Amazon EKS reserves a small set of prefixes that collide with well-known hostnames, such as `www`, `api`, and `admin`. This set can change. If you specify a reserved prefix, the request fails with an `InvalidParameterException` that names the prefix. If another capability in your AWS account and AWS Region already uses the prefix, the request fails with a `ResourceInUseException`. + +To specify a prefix, include `endpointPrefix` in the `argoCd` object that you pass to the `--configuration` parameter of `aws eks create-capability`. The following example uses the prefix `payments`: + + + { + "argoCd": { + "endpointPrefix": "payments", + "awsIdc": { + "idcInstanceArn": "arn:aws:sso:::instance/ssoins-1234567890abcdef", + "idcRegion": "idc-region-code" + }, + "rbacRoleMappings": [{ + "role": "ADMIN", + "identities": [{ + "id": "user-id", + "type": "SSO_USER" + }] + }] + } + } + +For the complete procedure, see [Create an Argo CD capability using the AWS CLI](./argocd-create-cli.html). You can also specify the prefix when you create the capability in the AWS Management Console. For more information, see [Create an Argo CD capability using the Console](./argocd-create-console.html). In AWS CloudFormation, use the `EndpointPrefix` property of `Configuration.ArgoCd` in the `AWS::EKS::Capability` resource. + + + Resources: + ArgoCdCapability: + Type: AWS::EKS::Capability + Properties: + ClusterName: my-cluster + CapabilityName: my-argocd + Type: ARGOCD + RoleArn: arn:aws:iam::111122223333:role/ArgoCDCapabilityRole + DeletePropagationPolicy: RETAIN + Configuration: + ArgoCd: + EndpointPrefix: payments + AwsIdc: + IdcInstanceArn: arn:aws:sso:::instance/ssoins-1234567890abcdef + IdcRegion: idc-region-code + + +`EndpointPrefix` is a create-only property. Adding, changing, or removing it in a stack update replaces the capability: CloudFormation deletes the existing capability before it creates the new one, so Argo CD is unavailable until the new capability is active. + +If you don’t specify a prefix, the endpoint uses the default format. To confirm the prefix for a capability, add `--query 'capability.configuration.argoCd.endpointPrefix'` to the `describe-capability` command. The output includes this field only for capabilities that you created with a prefix. + +###### Important + +You can’t change the endpoint prefix after you create the capability. To use a different prefix, delete the capability and create a new one. This interrupts Argo CD deployments until the new capability is active. Before you delete the capability, review the deletion guidance in [Delete a capability](./working-with-capabilities.html#capabilities-delete). + +A prefix is scoped to your AWS account and AWS Region, not to a single cluster. The hash in the default hostname depends on your cluster name, but a prefix doesn’t. This means you can keep the same Argo CD endpoint when you move to a different cluster. For example, you can replace a hub cluster and give the new capability the same prefix. + +Only one capability at a time can use a prefix in an AWS account and AWS Region. Delete the old capability before you create the new one. After the capability finishes deleting, AWS releases its prefix. You can then reuse that prefix on any cluster in the same AWS account and AWS Region, and you get the same endpoint. Before you create the new capability, confirm that the old capability no longer appears in the `list-capabilities` output for its original cluster. The endpoint is unavailable between the two capabilities. + +The new capability is a separate Argo CD instance with its own configuration. Integrations that point at the endpoint, such as Git webhooks, DNS records, and CI jobs, reach the new instance. For more information, see the note in Argo CD endpoint URL. + @@ -136 +219 @@ Both commands return `dc855fdf`. -The endpoint hostname is not a secret, and knowing it doesn’t grant access to your Argo CD instance. The hostname exposes the same non-secret information that already appears in the capability Amazon Resource Name (ARN). The `create-capability`, `describe-capability`, and `list-capabilities` operations return this ARN. AWS Identity Center authentication and Argo CD role-based access control (RBAC) control access to the Argo CD UI and API. +The endpoint hostname is not a secret, and knowing it doesn’t grant access to your Argo CD instance. The default hostname exposes the same non-secret information that already appears in the capability Amazon Resource Name (ARN). The `create-capability`, `describe-capability`, and `list-capabilities` operations return this ARN. If you specify a custom endpoint prefix, the hostname also exposes the prefix that you chose. Don’t include sensitive information in an endpoint prefix. AWS Identity Center authentication and Argo CD role-based access control (RBAC) control access to the Argo CD UI and API.