kubectl bridge plugin

The kubectl bridge plugin runs the Bridge UI and API on your own machine. The plugin acts as your kubeconfig identity, the same way kubectl does. Client certificate, exec, OIDC, and token credentials all work. You do not create a service account or paste a token.

Use the plugin to:

• Open the Bridge UI.
• Migrate a GitLab resource to a GitLabCore.

The plugin writes the custom resources only. To deploy the instances you configure, an Operator with Bridge enabled must run in the cluster. For more information, see Try Bridge in a development environment.

Install the plugin

No release ships a binary of the plugin. Build it from the source of the GitLab Operator.

Prerequisites:

• Git, and kubectl.
• Go, Node.js with npm, and Task. The project pins their versions in mise.toml.

To install the plugin:

1. Clone the GitLab Operator project:

   shell

   git clone https://gitlab.com/gitlab-org/cloud-native/gitlab-operator.git
   cd gitlab-operator

2. Check out the branch of the Operator image you run. For the latest-bridge image, stay on the default branch.

3. Optional. If you use mise, install the pinned tool versions:

   shell

   mise install

4. Build and install the plugin:

   shell

   task install-kubectl-plugin

   The task builds the UI, then installs the kubectl-bridge binary with go install. The binary goes to $GOBIN when it is set, and to $(go env GOPATH)/bin otherwise. The task prints the path.

5. Add that directory to your PATH, because kubectl finds plugins on the PATH. For example, add this line to your shell profile:

   shell

   export PATH="$(go env GOPATH)/bin:$PATH"

6. Verify that kubectl finds the plugin:

   shell

   kubectl plugin list | grep kubectl-bridge

To update the plugin, pull the branch and run task install-kubectl-plugin again.

Start the Bridge UI

Prerequisites:

• Your kubeconfig identity has the verbs you need on gitlabcores.apps.gitlab.com, siphons.apps.gitlab.com, and orbits.apps.gitlab.com. To create, edit, and delete instances, grant get, list, watch, create, update, patch, and delete.
• Optional. To choose a namespace from a list in the form, your identity has list on namespaces. To create a namespace from the form, it also has create on namespaces.

To start the Bridge UI:

1. Run the plugin against your current kubeconfig context:

   shell

   kubectl bridge

   The plugin prints the identity it acts as and the URL, and opens the URL in your browser. The header of the UI shows Local kubeconfig identity. For the API documentation, open /docs on the same URL.

2. When you are done, stop the plugin with Control+C.

The plugin listens on 127.0.0.1:8090. When that port is busy, the plugin picks a free port and prints it.

To use another context on another port, without opening a browser:

kubectl bridge --context <your_context> --port 9000 --no-open

For all options, run kubectl bridge --help.

Reach the plugin from another host

To run the plugin in a container or on a remote host, bind a routable address with --address. The plugin prints a warning when the address is not loopback.

The plugin answers 403 to an API request addressed to a host name it does not expect. It accepts loopback names, such as localhost, and the bind address. To reach the plugin under another name, such as a DNS entry or a container host name, pass the name to --accept-hosts:

kubectl bridge --address 0.0.0.0 --accept-hosts bridge.example.com --no-open

The plugin also answers 403 to an API request that the browser marks as sent from another site. Clients that are not browsers, such as curl, are not affected.