Select GitLab agent for environment in CI job

Release notes

In order to use the Kubernetes dashboard, you need to select an agent for Kubernetes connection under the environment settings. Until now, we only supported selecting the agent either through the UI or - since version 17.5 - the GitLab API. It still remained unpleasant to set up a dashboard from GitLab CI. In version 17.6, we offer the ability to configure the agent connection using the environment.kubernetes.agent syntax.

In a future version we want to add support to specify a namespace and a Flux resource as CI configuration. You can follow the related work here.

Problem

When using the Kubernetes GitLab agent in a project to have it deployed as a review environment, the resulting deployment isn't automatically linked to any KAS agent, thus leaving the tab “Kubernetes dashboard” empty. Users have to manually edit the environment and select an agent to establish the link.

Ideally, users would like to avoid this step and have a default KAS agent automatically assigned, so that the dashboard is filled with the correct items, and readily usable after deployment. 

Steps to reproduce

• Deploy an environment to Kubernetes using CI
• Go to the environments page
• The Kubernetes dashboard says “No Kubernetes clusters configured”
• It's then necessary to click on “Edit environment” and select the GitLab agent, then select the namespace.

Proposal

Introduce an environment.kubernetes.agent: <agent-config-project-path:agent-name> CI key to select an agent in CI.

Existing workaround 

Calling the graphQL API from CI might be feasible (needs to check the authorization of the CI job token):

update_environment:
  after_script:
    - |
      MUTATION='
      mutation {
        environmentUpdate(input: {
          id: "gid://gitlab/Environment/<environment id>"
          clusterAgentId: "gid://gitlab/Clusters::Agent/<agent id>"
        }) {
          environment {
            id
            name
          }
          errors
        }
      }
      '
    - |
      curl --request POST \
        --header "Content-Type: application/json" \
        --header "Authorization: Bearer $CI_JOB_TOKEN" \
        --data "{\"query\": \"$(echo $MUTATION | tr -d '\n')\"}" \
        "https://gitlab.com/api/graphql" | jq

Where environment id and agent id are returned by queries like

query environment {
  project(fullPath: "my-group/my-project") {
    environment(name: "my-environment") {
     id
     clusterAgent {
        id
     }
    }
  }
}