Amplía la Atlas CLI con complementos personalizados

Cómo funcionan los complementos

Cada plugin de Atlas CLI consta de dos componentes:

• A manifest.yml archivo que describe el complemento y sus comandos

• Un binario ejecutable que Atlas CLI invoca cuando un usuario ejecuta un comando de plugin

Cuando ejecutas un comando de plugin, Atlas CLI lee el archivo manifiesto, identifica el binario correcto y lo ejecuta con los argumentos adecuados. El binario del plugin maneja toda la lógica de comandos de forma independiente.

Requisitos previos

Antes de comenzar, asegúrese de tener instalado lo siguiente:

• Ir. 1 21 o posterior

• Git

• La interfaz de línea de comandos(CLI) de Atlas. Consulte Instalar o actualizar la CLI de Atlas.

Crea tu primer plugin

git clone https://github.com/mongodb/atlas-cli-plugin-example.git
cd atlas-cli-plugin-example

atlas-cli-plugin-example/
├── cmd/
│   └── plugin/
│       └── main.go
├── internal/
├── manifest.template.yml
├── go.mod
├── go.sum
├── Makefile
├── .goreleaser.yaml
└── .github/
    └── workflows/
        └── release.yml

name: atlas-cli-plugin-example
description: this is an example plugin
version: $VERSION
github:
    owner: $GITHUB_REPOSITORY_OWNER
    name: $GITHUB_REPOSITORY_NAME
binary: $BINARY
commands:
    example:
        description: Root command of the atlas cli plugin example
        aliases:
            - example-alias-1
            - example-alias-2

package main
import (
    "fmt"
    "os"
    "github.com/spf13/cobra"
)
func main() {
    rootCmd := &cobra.Command{
        Use:   "example",
        Short: "An example Atlas CLI plugin",
        Run: func(cmd *cobra.Command, args []string) {
            fmt.Println("Hello from the Atlas CLI plugin!")
        },
    }
    if err := rootCmd.Execute(); err != nil {
        os.Exit(1)
    }
}

go build -o bin/binary ./cmd/plugin
BINARY=binary VERSION=1.0.0 \
  GITHUB_REPOSITORY_OWNER=$(git remote get-url origin | sed 's/.*[:/]\(.*\)\/.*/\1/') \
  GITHUB_REPOSITORY_NAME=$(basename -s .git $(git remote get-url origin)) \
  envsubst < manifest.template.yml > manifest.yml

PLUGIN_DIR=~/Library/Application\ Support/atlascli/plugins/atlas-cli-plugin-example
mkdir -p "$PLUGIN_DIR"
cp manifest.yml bin/binary "$PLUGIN_DIR/"

PLUGIN_DIR=~/.config/atlascli/plugins/atlas-cli-plugin-example
mkdir -p "$PLUGIN_DIR"
cp manifest.yml bin/binary "$PLUGIN_DIR/"

atlas example

Hello from the Atlas CLI plugin!

Personaliza tu plugin

Para crear tu propio plugin, modifica el ejemplo o empieza desde cero:

1. Actualiza manifest.template.yml con el nombre, la descripción y los comandos de tu plugin.

2. Implementa tu lógica de comando en Go (o en cualquier lenguaje que compile a un binario autónomo).

3. Asegúrate de que tu nombre de binario coincide con el campo binary en manifest.template.yml.

Distribuye tu plugin

Para distribuir tu plugin de manera que otras personas puedan instalarlo con el comando atlas plugin install, sigue estos pasos:

1. Haga el hosting de su plugin en un repositorio de GitHub.

2. Utiliza GoReleaser o una herramienta similar para crear lanzamientos en GitHub con binarios compilados para múltiples plataformas. El repositorio de ejemplo incluye una configuración de .goreleaser.yaml y un flujo de trabajo de GitHub Actions para lanzamientos automatizados.

3. Cree una etiqueta de lanzamiento siguiendo el versionado semántico (por ejemplo, v1.0.0).

Después de crear una versión de GitHub, los usuarios pueden instalar tu plugin:

atlas plugin install <github-owner>/<repository-name>

Usa un lenguaje de programación diferente

Si bien recomendamos Go con Cobra, puedes escribir plugins en cualquier lenguaje que compile a un binario ejecutable autónomo. Para un ejemplo de un plugin escrito en otro lenguaje, consulta el plugin de Rust de ejemplo repositorio en Github.

Tu plugin debe cumplir con los siguientes requisitos:

• Su binario debe aceptar el nombre del comando como el primer argumento.

• Su binario debe ser un ejecutable autónomo (sin dependencias de tiempo de ejecución externas).

• El campo binary en manifest.yml debe coincidir con el nombre del archivo binario.

Obtén más información

• atlas plugin - Manage Atlas CLI plugins.

• atlas plugin install - Install a plugin.

• atlas plugin update - Update a plugin.

• atlas plugin uninstall - Uninstall a plugin.

• Repositorio de ejemplo de complemento de Atlas CLI

• Foros de MongoDB Community