GitLabgitlab-org

cli

main
ply8 git calls246 ms99 KiB5 cachedprotocol v2
128 lines8.1 KiBRaw

Bootstrap a GitLab Agent for Kubernetes in a project.

Synopsis

Bootstrap a GitLab Agent for Kubernetes (agentk) in a project.

The first argument must be the name of the agent.

It requires the kubectl and flux commands to be accessible via $PATH.

This command consists of multiple idempotent steps:

  1. Register the agent with the project.
  2. Configure the agent.
  3. Configure an environment with dashboard for the agent.
  4. Configure an environment with dashboard for FluxCD (if --create-flux-environment).
  5. Create a token for the agent.
    • If the agent has reached the maximum amount of tokens, the one that has not been used the longest is revoked and a new one is created.
    • If the agent has not reached the maximum amount of tokens, a new one is created.
  6. Push the Kubernetes Secret that contains the token to the cluster.
  7. Create Flux HelmRepository and HelmRelease resources.
  8. Commit and Push the created Flux Helm resources to the manifest path.
  9. Trigger Flux reconciliation of GitLab Agent HelmRelease (unless --no-reconcile).
plaintext
glab cluster agent bootstrap <agent-name> [flags]

Aliases

plaintext
bs

Examples

console
# Bootstrap "my-agent" to the root of the Git project in CWD, and trigger reconciliation
glab cluster agent bootstrap my-agent

# Bootstrap "my-agent" to "manifests/" of the Git project in CWD, and trigger reconciliation
# Especially useful when "flux bootstrap gitlab --path manifests/" is used.
# Make sure that the "--path" from the "flux bootstrap gitlab" command matches
# the "--manifest-path" of the "glab cluster agent bootstrap" command.
glab cluster agent bootstrap my-agent --manifest-path manifests/

# Bootstrap "my-agent" to "manifests/" of the Git project in CWD, and do not manually trigger a reconilication
glab cluster agent bootstrap my-agent --manifest-path manifests/ --no-reconcile

# Bootstrap "my-agent" without configuring an environment
glab cluster agent bootstrap my-agent --create-environment=false

# Bootstrap "my-agent" and configure an environment with custom name and Kubernetes namespace
glab cluster agent bootstrap my-agent --environment-name production --environment-namespace default

# Bootstrap "my-agent" without configuring a FluxCD environment
glab cluster agent bootstrap my-agent --create-flux-environment=false

# Bootstrap "my-agent" and configure a FluxCD environment with custom name and Kubernetes namespace
glab cluster agent bootstrap my-agent --flux-environment-name production-flux --flux-environment-namespace flux-system

# Bootstrap "my-agent" and pass additional GitLab Helm Chart values from a local file
glab cluster agent bootstrap my-agent --helm-release-values values.yaml

# Bootstrap "my-agent" and pass additional GitLab Helm Chart values from a Kubernetes ConfigMap
glab cluster agent bootstrap my-agent --helm-release-values-from ConfigMap/agent-config

# Bootstrap "my-agent" and commit with custom user
glab cluster agent bootstrap my-agent --commit-author-name="Tanuki" --commit-author-email="tanuki@example.com"

# Bootstrap "my-agent" with authenticated API user
glab cluster agent bootstrap my-agent --use-api-commit-author

Options

plaintext
      --commit-author-email string                   The Git commit author email to use. Conflicts with '--use-api-commit-author'. (default "noreply@glab.gitlab.com")
      --commit-author-name string                    The Git commit author name to use. Conflicts with '--use-api-commit-author'. (default "glab")
      --create-environment                           Create an environment for the GitLab Agent. (default true)
      --create-flux-environment                      Create an environment for FluxCD. Affects only the environment creation, not the use of Flux itself. Flux is always required for the bootstrap process. (default true)
      --environment-flux-resource-path string        Flux resource path of the environment for the GitLab Agent. (default "helm.toolkit.fluxcd.io/v2beta1/namespaces/<helm-release-namespace>/helmreleases/<helm-release-name>")
      --environment-name string                      Name of the environment for the GitLab Agent. (default "<helm-release-namespace>/<helm-release-name>")
      --environment-namespace string                 Kubernetes namespace of the environment for the GitLab Agent. (default "<helm-release-namespace>")
      --flux-environment-flux-resource-path string   Flux resource path of the environment for FluxCD. (default "kustomize.toolkit.fluxcd.io/v1/namespaces/flux-system/kustomizations/flux-system")
      --flux-environment-name string                 Name of the environment for FluxCD. (default "<flux-source-namespace>/<flux-source-name>")
      --flux-environment-namespace string            Kubernetes namespace of the environment for FluxCD. (default "<flux-source-namespace>")
      --flux-source-name string                      Flux source name. (default "flux-system")
      --flux-source-namespace string                 Flux source namespace. (default "flux-system")
      --flux-source-type string                      Source type of the flux-system, like Git, OCI, or Helm. (default "git")
      --gitlab-agent-token-secret-name string        Name of the Secret where the token for the GitLab Agent is stored. The helm-release-target-namespace is implied for the namespace of the Secret. (default "gitlab-agent-token")
      --helm-release-filepath string                 File path within the GitLab Agent project to commit the Flux HelmRelease to. (default "gitlab-agent-helm-release.yaml")
      --helm-release-name string                     Name of the Flux HelmRelease manifest. (default "gitlab-agent")
      --helm-release-namespace string                Namespace of the Flux HelmRelease manifest. (default "flux-system")
      --helm-release-target-namespace string         Namespace of the GitLab Agent deployment. (default "gitlab-agent")
      --helm-release-values strings                  Local path to values.yaml files. Multiple files can be comma-separated or specified by repeating the flag.
      --helm-release-values-from strings             Kubernetes object reference that contains the values.yaml data key in the format '<kind>/<name>', where 'kind' must be one of: (Secret, ConfigMap). Multiple references can be comma-separated or specified by repeating the flag.
      --helm-repository-address string               Address of the HelmRepository. (default "https://charts.gitlab.io")
      --helm-repository-filepath string              File path within the GitLab Agent project to commit the Flux HelmRepository to. (default "gitlab-helm-repository.yaml")
      --helm-repository-name string                  Name of the Flux HelmRepository manifest. (default "gitlab")
      --helm-repository-namespace string             Namespace of the Flux HelmRepository manifest. (default "flux-system")
  -b, --manifest-branch string                       Branch to commit the Flux Manifests to. Defaults to the project default branch.
  -p, --manifest-path string                         Location of directory in Git repository for storing the GitLab Agent for Kubernetes Helm resources.
      --no-reconcile                                 Do not trigger Flux reconciliation for GitLab Agent for Kubernetes Flux resource.
      --use-api-commit-author                        When creating Git commits use the user from the authenticated API request. Conflicts with '--commit-author-name' and '--commit-author-email'.

Options inherited from parent commands

plaintext
  -h, --help          Show help for this command.
  -R, --repo string   Select another repository. You can use either OWNER/REPO or GROUP/NAMESPACE/REPO. The full URL or Git URL is also accepted.
1---
2title: '`glab cluster agent bootstrap`'
3stage: AI Clients
4group: Developer Clients
5info: To determine the technical writer assigned to the Stage/Group associated with this page, see <https://handbook.gitlab.com/handbook/marketing/product-and-technical-marketing/technical-writing/#assignments>
6---
8<!--
9This documentation is auto generated by a script.
10Please do not edit this file directly. Run `make gen-docs` instead.
11-->
13Bootstrap a GitLab Agent for Kubernetes in a project.
15## Synopsis
17Bootstrap a GitLab Agent for Kubernetes (agentk) in a project.
19The first argument must be the name of the agent.
21It requires the `kubectl` and `flux` commands to be accessible via `$PATH`.
23This command consists of multiple idempotent steps:
251. Register the agent with the project.
262. Configure the agent.
273. Configure an environment with dashboard for the agent.
284. Configure an environment with dashboard for FluxCD (if `--create-flux-environment`).
295. Create a token for the agent.
30 - If the agent has reached the maximum amount of tokens,
31 the one that has not been used the longest is revoked
32 and a new one is created.
33 - If the agent has not reached the maximum amount of tokens,
34 a new one is created.
356. Push the Kubernetes Secret that contains the token to the cluster.
367. Create Flux HelmRepository and HelmRelease resources.
378. Commit and Push the created Flux Helm resources to the manifest path.
389. Trigger Flux reconciliation of GitLab Agent HelmRelease (unless `--no-reconcile`).
40```plaintext
41glab cluster agent bootstrap <agent-name> [flags]
42```
44## Aliases
46```plaintext
47bs
48```
50## Examples
52```console
53# Bootstrap "my-agent" to the root of the Git project in CWD, and trigger reconciliation
54glab cluster agent bootstrap my-agent
56# Bootstrap "my-agent" to "manifests/" of the Git project in CWD, and trigger reconciliation
57# Especially useful when "flux bootstrap gitlab --path manifests/" is used.
58# Make sure that the "--path" from the "flux bootstrap gitlab" command matches
59# the "--manifest-path" of the "glab cluster agent bootstrap" command.
60glab cluster agent bootstrap my-agent --manifest-path manifests/
62# Bootstrap "my-agent" to "manifests/" of the Git project in CWD, and do not manually trigger a reconilication
63glab cluster agent bootstrap my-agent --manifest-path manifests/ --no-reconcile
65# Bootstrap "my-agent" without configuring an environment
66glab cluster agent bootstrap my-agent --create-environment=false
68# Bootstrap "my-agent" and configure an environment with custom name and Kubernetes namespace
69glab cluster agent bootstrap my-agent --environment-name production --environment-namespace default
71# Bootstrap "my-agent" without configuring a FluxCD environment
72glab cluster agent bootstrap my-agent --create-flux-environment=false
74# Bootstrap "my-agent" and configure a FluxCD environment with custom name and Kubernetes namespace
75glab cluster agent bootstrap my-agent --flux-environment-name production-flux --flux-environment-namespace flux-system
77# Bootstrap "my-agent" and pass additional GitLab Helm Chart values from a local file
78glab cluster agent bootstrap my-agent --helm-release-values values.yaml
80# Bootstrap "my-agent" and pass additional GitLab Helm Chart values from a Kubernetes ConfigMap
81glab cluster agent bootstrap my-agent --helm-release-values-from ConfigMap/agent-config
83# Bootstrap "my-agent" and commit with custom user
84glab cluster agent bootstrap my-agent --commit-author-name="Tanuki" --commit-author-email="tanuki@example.com"
86# Bootstrap "my-agent" with authenticated API user
87glab cluster agent bootstrap my-agent --use-api-commit-author
88```
90## Options
92```plaintext
93 --commit-author-email string The Git commit author email to use. Conflicts with '--use-api-commit-author'. (default "noreply@glab.gitlab.com")
94 --commit-author-name string The Git commit author name to use. Conflicts with '--use-api-commit-author'. (default "glab")
95 --create-environment Create an environment for the GitLab Agent. (default true)
96 --create-flux-environment Create an environment for FluxCD. Affects only the environment creation, not the use of Flux itself. Flux is always required for the bootstrap process. (default true)
97 --environment-flux-resource-path string Flux resource path of the environment for the GitLab Agent. (default "helm.toolkit.fluxcd.io/v2beta1/namespaces/<helm-release-namespace>/helmreleases/<helm-release-name>")
98 --environment-name string Name of the environment for the GitLab Agent. (default "<helm-release-namespace>/<helm-release-name>")
99 --environment-namespace string Kubernetes namespace of the environment for the GitLab Agent. (default "<helm-release-namespace>")
100 --flux-environment-flux-resource-path string Flux resource path of the environment for FluxCD. (default "kustomize.toolkit.fluxcd.io/v1/namespaces/flux-system/kustomizations/flux-system")
101 --flux-environment-name string Name of the environment for FluxCD. (default "<flux-source-namespace>/<flux-source-name>")
102 --flux-environment-namespace string Kubernetes namespace of the environment for FluxCD. (default "<flux-source-namespace>")
103 --flux-source-name string Flux source name. (default "flux-system")
104 --flux-source-namespace string Flux source namespace. (default "flux-system")
105 --flux-source-type string Source type of the flux-system, like Git, OCI, or Helm. (default "git")
106 --gitlab-agent-token-secret-name string Name of the Secret where the token for the GitLab Agent is stored. The helm-release-target-namespace is implied for the namespace of the Secret. (default "gitlab-agent-token")
107 --helm-release-filepath string File path within the GitLab Agent project to commit the Flux HelmRelease to. (default "gitlab-agent-helm-release.yaml")
108 --helm-release-name string Name of the Flux HelmRelease manifest. (default "gitlab-agent")
109 --helm-release-namespace string Namespace of the Flux HelmRelease manifest. (default "flux-system")
110 --helm-release-target-namespace string Namespace of the GitLab Agent deployment. (default "gitlab-agent")
111 --helm-release-values strings Local path to values.yaml files. Multiple files can be comma-separated or specified by repeating the flag.
112 --helm-release-values-from strings Kubernetes object reference that contains the values.yaml data key in the format '<kind>/<name>', where 'kind' must be one of: (Secret, ConfigMap). Multiple references can be comma-separated or specified by repeating the flag.
113 --helm-repository-address string Address of the HelmRepository. (default "https://charts.gitlab.io")
114 --helm-repository-filepath string File path within the GitLab Agent project to commit the Flux HelmRepository to. (default "gitlab-helm-repository.yaml")
115 --helm-repository-name string Name of the Flux HelmRepository manifest. (default "gitlab")
116 --helm-repository-namespace string Namespace of the Flux HelmRepository manifest. (default "flux-system")
117 -b, --manifest-branch string Branch to commit the Flux Manifests to. Defaults to the project default branch.
118 -p, --manifest-path string Location of directory in Git repository for storing the GitLab Agent for Kubernetes Helm resources.
119 --no-reconcile Do not trigger Flux reconciliation for GitLab Agent for Kubernetes Flux resource.
120 --use-api-commit-author When creating Git commits use the user from the authenticated API request. Conflicts with '--commit-author-name' and '--commit-author-email'.
121```
123## Options inherited from parent commands
125```plaintext
126 -h, --help Show help for this command.
127 -R, --repo string Select another repository. You can use either OWNER/REPO or GROUP/NAMESPACE/REPO. The full URL or Git URL is also accepted.
128```
Diagnostics8 git calls · 246 ms
CallStatusSizeTime0246 ms
discover200185 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=185
git.server.agent=git/2.56.g1891de4-Linux
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch server-option object-format
git.server.fetch=shallow wait-for-done filter
git.protocol.version=2
git.pkt.frames=9
git.pkt.data=7
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=185
git.pkt.payload.max=35
ls-refs20058 KiB2 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=59849
git.response.cache=UPDATING
git.response.duration_ms=2
git.protocol.version=2
git.pkt.frames=731
git.pkt.data=730
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=59849
git.pkt.payload.max=143
git.ls_refs.count=730
git.ls_refs.head=refs/heads/main
fetchtree:0 · deepen 1020032 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=4
git.response.bytes=32926
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=tree:0
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=22
git.pkt.data=20
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=32926
git.pkt.payload.max=32046
git.sideband.band1.bytes=32046
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=80
git.pack.bytes=32046
git.pack.ofs_delta=36
git.pack.ref_delta=0
git.pack.chain.max=2
git.pack.trailer=cb0bad5d7ffc514895d8b21c4dd470327f90bc91
git.pack.full=44
Open pack map
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit4 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=4273
git.response.cache=HIT
git.response.duration_ms=4
git.fetch.filter=combine:blob:none+tree:2
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=1
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=7
git.pkt.data=5
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=4273
git.pkt.payload.max=4173
git.sideband.band1.bytes=4173
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=11
git.pack.bytes=4173
git.fetch.wide.objects=11
git.fetch.wide.extra_bytes=3930
git.fetch.wide.blobs=0
fetchtree:02001.7 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=4
git.response.bytes=1744
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=5e4007a5673eb3bf5d0d7f1a1463c3b2ca3fb3bd
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=1744
git.pkt.payload.max=1717
git.sideband.band1.bytes=1717
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=1717
git.pack.trailer=3f1b9ccc7756e8941d6705e8187c87fd922113e6
Open pack map
fetchtree:0200171 B · hit4 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=19
git.response.bytes=171
git.response.cache=HIT
git.response.duration_ms=4
git.fetch.filter=tree:0
git.fetch.wants=deb8abea1ce2956a8875db697874c5f77b7d5ca9
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=171
git.pkt.payload.max=144
git.sideband.band1.bytes=144
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=144
git.pack.trailer=1230c2ed51d56fb4bf9715659a42d5c9953cfde8
Open pack map
fetchtree:0200350 B · hit19 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=213
git.response.bytes=350
git.response.cache=HIT
git.response.duration_ms=19
git.fetch.filter=tree:0
git.fetch.wants=69e9920cf72f76159b96d19be4f9029f62aca2e3
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=350
git.pkt.payload.max=323
git.sideband.band1.bytes=323
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=323
git.pack.trailer=ba5bc87328c78159ce58989f4ee10db3de10e38e
Open pack map
fetch2002.2 KiB213 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=2300
git.response.cache=MISS
git.response.duration_ms=213
git.fetch.wants=71eba975173919336bb89e76edc83834ee6eaa88
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=2300
git.pkt.payload.max=2273
git.sideband.band1.bytes=2273
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://gitlab.com/gitlab-org/cli
Ref
refs/heads/main
Commit
0dd7574dce9e385c5c30540e6c15657adc6bdce9
cf-ray
a5e19ad76a43b86e
Request
50e27604…
Protocol
v2 · sha1
Agent
git/2.56.g1891de4-Linux
Filter
advertised
Fetch
shallow wait-for-done filter
Capabilities
agent ls-refs fetch server-option object-format