Skip to content

Latest commit

 

History

History
219 lines (149 loc) · 7 KB

fleeting.md

File metadata and controls

219 lines (149 loc) · 7 KB
stage group info title
Verify
Runner
To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
Fleeting

Fleeting is a library that GitLab Runner uses to provide a plugin-based abstraction for a cloud provider's instance groups.

The following executors use fleeting to scale runners:

GitLab maintains these official plugins:

Cloud provider Notes
Google Cloud Uses Google Cloud instance groups
AWS Uses AWS Auto Scaling groups
Azure Uses Azure Virtual Machine Scale Sets. Only Uniform orchestration mode is supported.

To configure fleeting, in the config.toml, use the [runners.autoscaler] configuration section.

{{< alert type="note" >}}

The README.md file for each plugin contains important information regarding installation and configuration.

{{< /alert >}}

Install a fleeting plugin

To install a fleeting plugin, use either the:

  • OCI registry distribution (recommended)
  • Manual binary installation

Install with the OCI registry distribution

{{< history >}}

  • Introduced OCI registry distribution in GitLab Runner 16.11

{{< /history >}}

Plugins are installed to ~/.config/fleeting/plugins on UNIX systems, and %APPDATA%/fleeting/plugins on Windows. To override where plugins are installed, update the environment variable FLEETING_PLUGIN_PATH.

To install the fleeting plugin:

  1. In the config.toml, in the [runners.autoscaler] section, add the fleeting plugin:

    {{< tabs >}}

    {{< tab title="AWS" >}}

    [[runners]]
  name = "my runner"
  url = "https://gitlab.com"
  token = "<token>"
  shell = "sh"

executor = "instance"

[runners.autoscaler]
  plugin = "aws:latest"

    {{< /tab >}}

    {{< tab title="Google Cloud" >}}

    [[runners]]
  name = "my runner"
  url = "https://gitlab.com"
  token = "<token>"
  shell = "sh"

executor = "instance"

[runners.autoscaler]
  plugin = "googlecloud:latest"

    {{< /tab >}}

    {{< tab title="Azure" >}}

    [[runners]]
  name = "my runner"
  url = "https://gitlab.com"
  token = "<token>"
  shell = "sh"

executor = "instance"

[runners.autoscaler]
  plugin = "azure:latest"

    {{< /tab >}}

    {{< /tabs >}}

  2. Run gitlab-runner fleeting install.

plugin formats

The plugin parameter supports the following formats:

  • <name>
  • <name>:<version constraint>
  • <repository>/<name>
  • <repository>/<name>:<version constraint>
  • <registry>/<repository>/<name>
  • <registry>/<repository>/<name>:<version constraint>

Where:

  • registry.gitlab.com is the default registry.
  • gitlab-org/fleeting/plugins is the default repository.
  • latest is the default version.

Version constraint formats

The gitlab-runner fleeting install command uses the version constraint to find the latest matching version in the remote repository.

When GitLab Runner runs, it uses the version constraint to find the latest matching version that is installed locally.

Use the following version constraint formats:

Format Description
latest Latest version.
<MAJOR> Selects the major version. For example, 1 selects the version that matches 1.*.*.
<MAJOR>.<MINOR> Selects the major and minor version. For example, 1.5 selects the latest version that matches 1.5.*.
<MAJOR>.<MINOR>.<PATCH> Selects the major and minor version, and patch. For example, 1.5.1 selects the version 1.5.1.

Install binary manually

To manually install a fleeting plugin:

  1. Download the fleeting plugin binary for your system:

  2. Ensure the binary has a name in the format of fleeting-plugin-<name>. For example, fleeting-plugin-aws.

  3. Ensure the binary can be discovered from $PATH. For example, move it to /usr/local/bin.

  4. In the config.toml, in the [runners.autoscaler] section, add the fleeting plugin. For example:

    {{< tabs >}}

    {{< tab title="AWS" >}}

    [[runners]]
  name = "my runner"
  url = "https://gitlab.com"
  token = "<token>"
  shell = "sh"

executor = "instance"

[runners.autoscaler]
  plugin = "fleeting-plugin-aws"

    {{< /tab >}}

    {{< tab title="Google Cloud" >}}

    [[runners]]
name = "my runner"
url = "https://gitlab.com"
token = "<token>"
shell = "sh"

executor = "instance"

[runners.autoscaler]
plugin = "fleeting-plugin-googlecloud"

    {{< /tab >}}

    {{< tab title="Azure" >}}

    [[runners]]
name = "my runner"
url = "https://gitlab.com"
token = "<token>"
shell = "sh"

executor = "instance"

[runners.autoscaler]
plugin = "fleeting-plugin-azure"

    {{< /tab >}}

    {{< /tabs >}}

Fleeting plugin management

Use the following fleeting subcommands to manage fleeting plugins:

Command Description
gitlab-runner fleeting install Install the fleeting plugin from the OCI registry distribution.
gitlab-runner fleeting list List referenced plugins and the version used.
gitlab-runner fleeting login Sign in to private registries.