orchestrator is an internal gem; it is not published on rubygems. Run orchestrator by prefixing commands with bundle exec within its directory, for example:

$ bundle exec orchestrator help

Commands:
  orchestrator create [SUBCOMMAND]   # Manage deployment related object creation
  orchestrator destroy [SUBCOMMAND]  # Manage deployment related object cleanup
  orchestrator doctor                # Validate presence of all required system dependencies
  orchestrator help [COMMAND]        # Describe available commands or one specific command
  orchestrator log [SUBCOMMAND]      # Manage deployment related logs
  orchestrator version               # Print orchestrator version

Example commands

1) Create a Cloud Native GitLab deployment (Helm-based)

$ bundle exec orchestrator create deployment kind

This command spins up a Kubernetes cluster using kind and deploys GitLab via the Helm chart.

2) Create a Docker-based GitLab Omnibus instance

$ bundle exec orchestrator create instance gitlab

This command launches a local container using the GitLab Docker image.

Environment variables

It is possible to configure certain options via environment variables. Following environment variables are supported:

ORCHESTRATOR_FORCE_COLOR - force color output in case support is not detected properly (useful for CI executions)
CNG_HELM_REPOSITORY_CACHE - custom helm repository cache folder. Equivalent to global --repository-cache flag of helm command

Add new deployments

The main feature orchestrator is to programmatically manage different deployment type configurations and setup. To implement new deployment configuration:

Add a new subcommand method to the Deployment class. This allows you to to define your own input arguments and documentation.
Define a configuration class based on the Base configuration class. You can implement:
- pre-deployment setup: optional setup steps that are executed before installing the GitLab instance.
- post-deployment setup: optional setup steps that are executed after instance of GitLab has been installed.
- helm values: set of values to apply during installation.
Define a cleanup class based on the Base cleanup class. Implement a single method that deletes all objects created by pre-deployment and post-deployment setup.

All different options for GitLab deployment on Kubernetes cluster are described in GitLab Helm chart documentation page.

Tips

kubectl context

orchestrator CLI uses kubectl and Helm to perform all kubernetes-related operations. When running a deployment, current context is always used. If non-default arguments are used when running the deployment, make sure current context points to the cluster where the deployment should be executed.

Shell integration

To make orchestrator globally available in your shell without the need to run the commands from a specific folder and prefixed with bundle exec, add the following function to your shell's configuration file (for example,.zshrc or .bash_profile):

function orchestrator() {
  (cd $PATH_TO_GITLAB_REPO/gems/gitlab-orchestrator && BUNDLE_AUTO_INSTALL=true bundle exec orchestrator "$@")
}

Troubleshooting

Helm deployment

Because orchestrator tool essentially wraps helm upgrade --install command, official Troubleshooting the GitLab chart guide can be used for troubleshooting deployment failures.

CI setup

Documentation on where to find environment logs and other useful information for troubleshooting failures on CI can be found in test pipelines documentation section.