diff --git a/src/pages/docs/argo-cd/annotations/index.md b/src/pages/docs/argo-cd/annotations/index.md index b9872a3d41..c87a49204d 100644 --- a/src/pages/docs/argo-cd/annotations/index.md +++ b/src/pages/docs/argo-cd/annotations/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2025-09-15 -modDate: 2025-09-15 +modDate: 2026-07-21 title: Scoping Annotations description: What annotations are required to link Argo CD applications to Octopus Projects/Environments/Tenants navTitle: Scoping Annotations @@ -93,6 +93,33 @@ spec: name: guestbook-service-2 ``` +## Scoping applications to spaces + +When a gateway is [registered in multiple spaces](/docs/argo-cd/instances/automated-installation#registering-a-gateway-in-multiple-spaces), applications from that Argo CD instance appear in every space the gateway is registered in. If an application should only appear in some of those spaces, add the `argo.octopus.com/space` annotation. + +| Annotation | Required | Value description | +| ------------------------ | -------- | ------------------------------------------------------------- | +| `argo.octopus.com/space` | false | A comma-separated list of Octopus Space *slugs* | + +The space annotation applies to the whole application and cannot be source-scoped. If the annotation is not present, the application appears in all spaces the gateway is registered in, so you only need it when application names would collide across spaces. + +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: guestbook + namespace: argocd + annotations: + argo.octopus.com/space: space-one, space-two + argo.octopus.com/environment: development + argo.octopus.com/project: argo-cd-guestbook +spec: + source: + repoURL: https://github.com/example-org/guestbook.git + targetRevision: HEAD + path: ./ +``` + ## Updating in Argo CD Web UI You can update the annotations for an Argo CD Application via the Argo CD Web UI. diff --git a/src/pages/docs/argo-cd/instances/automated-installation.md b/src/pages/docs/argo-cd/instances/automated-installation.md index 0b771cd880..faba3aed43 100644 --- a/src/pages/docs/argo-cd/instances/automated-installation.md +++ b/src/pages/docs/argo-cd/instances/automated-installation.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2025-09-15 -modDate: 2026-03-26 +modDate: 2026-07-21 title: Automated Installation description: Install Argo CD instances via scripting or IAC navOrder: 10 @@ -111,6 +111,51 @@ resource "helm_release" "argo_gateway" { } ``` +## Registering a gateway in multiple spaces + +From `2026.3.7755` onwards, a single gateway installation can be registered in more than one space, making the same Argo CD instance available in each of them. + +By default, every registered space discovers all of the instance's applications. To limit an application to specific spaces, use the [space scoping annotation](/docs/argo-cd/annotations#scoping-applications-to-spaces). + +### Using Helm values + +Set `registration.octopus.spaceIds` and the gateway registers itself into each listed space: + +```bash +--set 'registration.octopus.spaceIds={Spaces-1,Spaces-2,Spaces-3}' \ +``` + +### Using the REST API + +You can also register an already-installed gateway in another space with the REST API by setting `PreserveAuthenticationToken` to `true`. + +First, find the gateway's client ID by getting its registration from the space it was initially installed into. The gateway ID (e.g. `ArgoCDGateways-1`) is shown in the URL of the Argo CD instance page in Octopus. + +```bash +curl -H "X-Octopus-ApiKey: API-YOUR-KEY" \ + "https://your-octopus-url/api/Spaces-1/argocdgateways/ArgoCDGateways-1" +``` + +The response includes a `ClientId` value, which is used to re-register the gateway in the new space. To run the registration in a new space: + +```bash +curl -X POST \ + -H "X-Octopus-ApiKey: API-YOUR-KEY" \ + -H "Content-Type: application/json" \ + "https://your-octopus-url/api//argocdgateways" \ + -d '{ + "SpaceId": "", + "ClientId": "", + "Name": "", + "Environments": [], + "PreserveAuthenticationToken": true + }' +``` + +When `PreserveAuthenticationToken` is `true`, the response's `AuthenticationToken` is null and the existing token remains valid. + +Deleting a registration only removes the gateway from that space. The gateway's authentication token stays valid while it's registered in at least one space. + ## Installing as an Argo CD Application The Octopus-Argo Gateway's helm chart can be installed via an Argo CD Application. @@ -119,61 +164,61 @@ The application YAML required to install the helm chart is as follows (replacing 1. Create the namespace - ```shell - kubectl create ns octopus-argo-gateway-your-namespace - ``` + ```shell + kubectl create ns octopus-argo-gateway-your-namespace + ``` 2. Generate Argo CD Authentication Token - 2.1. Follow the instructions on the [Argo CD Authentication](/docs/argo-cd/instances/argo-user) guide - 2.2. Save the token in a secret + 2.1. Follow the instructions on the [Argo CD Authentication](/docs/argo-cd/instances/argo-user) guide + 2.2. Save the token in a secret - ```shell - kubectl create secret generic argocd-auth-token -n octopus-argo-gateway-your-namespace --from-literal=ARGOCD_AUTH_TOKEN= - ``` + ```shell + kubectl create secret generic argocd-auth-token -n octopus-argo-gateway-your-namespace --from-literal=ARGOCD_AUTH_TOKEN= + ``` 3. Generate Octopus Deploy Api-Key - 3.1. Follow the instructions on the [How to Create an API Key](/docs/octopus-rest-api/how-to-create-an-api-key) guide - 3.2. Save the token in a secret + 3.1. Follow the instructions on the [How to Create an API Key](/docs/octopus-rest-api/how-to-create-an-api-key) guide + 3.2. Save the token in a secret - ```shell - kubectl create secret generic octopus-server-access-token -n octopus-argo-gateway-your-namespace --from-literal=OCTOPUS_SERVER_ACCESS_TOKEN= - ``` + ```shell + kubectl create secret generic octopus-server-access-token -n octopus-argo-gateway-your-namespace --from-literal=OCTOPUS_SERVER_ACCESS_TOKEN= + ``` 4. Apply the Argo CD application (or commit this manifest to your git-ops repository already synced by Argo CD) - ```yaml - apiVersion: argoproj.io/v1alpha1 - kind: Application - metadata: - finalizers: - - resources-finalizer.argocd.argoproj.io - name: octopus-argo-gateway - spec: - project: default - source: - repoURL: registry-1.docker.io/octopusdeploy - chart: octopus-argocd-gateway-chart - targetRevision: 1.23.0 - helm: - valuesObject: - registration: - octopus: - name: - serverApiUrl: https://your-instance.octopus.app - serverAccessTokenSecretName: octopus-server-access-token - serverAccessTokenSecretKey: OCTOPUS_SERVER_ACCESS_TOKEN - spaceId: Spaces-1 - gateway: - octopus: - serverGrpcUrl: grpc://your-instance.octopus.app:8443 - argocd: - serverGrpcUrl: grpc://argocd-server.argocd.svc.cluster.local - authenticationTokenSecretName: argocd-auth-token - authenticationTokenSecretKey: ARGOCD_AUTH_TOKEN - autoUpdate: - # should be disabled, otherwise the auto-update job will keep trying to update the instance, while argo cd syncs it back to original state - enabled: false - destination: - server: https://kubernetes.default.svc - namespace: octopus-argo-gateway-your-namespace - ``` + ```yaml + apiVersion: argoproj.io/v1alpha1 + kind: Application + metadata: + finalizers: + - resources-finalizer.argocd.argoproj.io + name: octopus-argo-gateway + spec: + project: default + source: + repoURL: registry-1.docker.io/octopusdeploy + chart: octopus-argocd-gateway-chart + targetRevision: 1.23.0 + helm: + valuesObject: + registration: + octopus: + name: + serverApiUrl: https://your-instance.octopus.app + serverAccessTokenSecretName: octopus-server-access-token + serverAccessTokenSecretKey: OCTOPUS_SERVER_ACCESS_TOKEN + spaceId: Spaces-1 + gateway: + octopus: + serverGrpcUrl: grpc://your-instance.octopus.app:8443 + argocd: + serverGrpcUrl: grpc://argocd-server.argocd.svc.cluster.local + authenticationTokenSecretName: argocd-auth-token + authenticationTokenSecretKey: ARGOCD_AUTH_TOKEN + autoUpdate: + # should be disabled, otherwise the auto-update job will keep trying to update the instance, while argo cd syncs it back to original state + enabled: false + destination: + server: https://kubernetes.default.svc + namespace: octopus-argo-gateway-your-namespace + ```