Estenda o Atlas CLI com plug-ins personalizados

Como funcionam os plugins

Cada plugin do Atlas CLI consiste em dois componentes:

• Um arquivo manifest.yml que descreve o plugin-in e seus comandos

• Um binário executável que o Atlas CLI invoca quando um usuário executa um comando de plugin

Quando você executa um comando de plugin , o Atlas CLI lê o arquivo de manifesto, identifica o binário correto e o executa com os argumentos apropriados. O binário do plugin lida com toda a lógica de comando de forma independente.

Pré-requisitos

Antes de começar, verifique se você tem o seguinte instalado:

• 1Vá.21 ou posterior

• Git

• O Atlas CLI.Consulte Instalar ou Atualizar o Atlas CLI.

Criar seu primeiro 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!

Personalizar plug-in

Para criar seu próprio plugin-in, modifique o exemplo ou comece do zero:

1. Atualize manifest.template.yml com o nome, descrição e comandos do seu plugin.

2. Implemente sua lógica de comando no Go (ou em qualquer linguagem que seja compilada para um binário autônomo ).

3. Certifique-se de que seu nome binário corresponda ao campo binary em manifest.template.yml.

Distribuir seu plug-in

Para distribuir seu plugin para que outros possam instalá-lo com o comando atlas plugin install, siga estas etapas:

1. Hospede seu plugin em um repositório do GitHub.

2. Use o GoReleaser ou uma ferramenta semelhante para criar versões do GitHub com binários compilados para várias plataformas. O repositório de exemplo inclui uma .goreleaser.yaml configuração do e um fluxo de trabalho do GitHub Actions para versões automatizadas.

3. Crie uma tag de versão após a versão semântica (porv1.0.0 exemplo,).

Depois de criar uma versão do GitHub, os usuários podem instalar seu plugin-in:

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

Use uma linguagem de programação diferente

Embora recomendamos o Go with Cobra, você pode escrever plugins em qualquer linguagem que se compile para um binário executável autônomo . Para obter um exemplo de um plugin-in escrito em uma linguagem diferente, consulte o exemplo de repositório de plugin Rust no GitHub.

Seu plugin deve atender aos seguintes requisitos:

• Seu binário deve aceitar o nome do comando como o primeiro argumento.

• Seu binário deve ser um executável autônomo (sem dependências externas de tempo de execução).

• O campo binary em manifest.yml deve corresponder ao nome do arquivo binário.

Saiba mais

• atlas plugin - Manage Atlas CLI plugins.

• atlas plugin install - Install a plugin.

• atlas plugin update - Update a plugin.

• atlas plugin uninstall - Uninstall a plugin.

• Repositório de exemplo de plugin-in Atlas CLI

• Fóruns da comunidade do MongoDB