Integração de CI/CD com Snowflake CLI

Snowflake CLI integra sistemas e frameworks populares de CI/CD (integração contínua e entrega contínua), como GitHub Actions, para automatizar com eficiência os fluxos de trabalho do Snowflake para SQL, Snowpark, Native Apps ou Notebooks.

A ilustração a seguir mostra um fluxo de trabalho típico de CI/CD no Snowflake CLI.

Fluxo de trabalho de CI/CD do Snowflake

Etapas do fluxo de trabalho de CI/CD

  1. Armazenar: configure um repositório Git remoto para gerenciar seus arquivos do Snowflake com segurança.

  2. Codificar: desenvolva seu código Snowflake usando um IDE ou Snowsight, adaptado às suas preferências.

  3. Instalar: Instale Snowflake CLI e provisione seu provedor preferido de CI/CD, como GitHub Actions.

  4. Implantar: automatize a implementação combinando o Snowflake CLI com sua ferramenta de CI/CD selecionada.

  5. Monitorar: acompanhe o desempenho do código e do fluxo de trabalho no Snowflake usando o Snowflake Trail para obter insights em tempo real.

  6. Iterar: aplique atualizações pequenas e frequentes ao seu projeto para melhoria contínua; mudanças menores simplificam o gerenciamento e a reversão, se necessário.

CI/CD com GitHub Actions

Uma ação Snowflake CLI é uma ação do GitHub para integrar Snowflake CLI em pipelines de CI/CD. Você pode usá-la para automatizar a execução de comandos Snowflake CLI nos seus fluxos de trabalho do GitHub. Para mais informações, consulte o repositório snowflake-cli-action.

Usar ações do Snowflake CLI

Github Actions simplificam o processo de instalação e uso do Snowflake CLI nos seus fluxos de trabalho de CI/CD. O CLI é instalado de forma isolada, garantindo que não entre em conflito com as dependências do seu projeto. Ele define automaticamente o arquivo de configuração de entrada dentro do diretório ~/.snowflake/.

A ação permite automatizar suas tarefas de CLI do Snowflake, como a implantação de Snowflake Native Apps ou a execução de scripts Snowpark em seu ambiente Snowflake.

Parâmetros de entrada

Uma ação do Snowflake CLI usa as seguintes entradas do arquivo YAML do seu fluxo de trabalho do Github, como <repo-name>/.github/workflows/my-workflow.yaml:

  • cli-version: A versão especificada do CLI do Snowflake, como 3.11.0. Se não tiver sido fornecida, será usada a versão mais recente do Snowflake CLI.

  • custom-github-ref: A ramificação, tag ou commit no repositório Github do qual você quer instalar o Snowflake CLI diretamente.

    Nota

    Não é possível usar cli-version e custom-github-ref juntos; especifique apenas um desses parâmetros.

  • default-config-file-path: Caminho para o arquivo de configuração (config.toml) em seu repositório. O caminho deve ser relativo à raiz do repositório. O arquivo de configuração não é necessário quando uma conexão temporária (opção -x) é usado. Para mais informações, consulte Gerenciando conexões Snowflake.

  • use-oidc: Sinalizador booliano para habilitar a autenticação OIDC. Quando definido como true, a ação configura o CLI para usar o token OIDC do GitHub para autenticação com o Snowflake, eliminando a necessidade de armazenar chaves privadas como segredos. O padrão é false.

Instalação do Snowflake CLI a partir de uma ramificação ou tag do GitHub

  • Para instalar o CLI do Snowflake a partir de uma ramificação, tag ou commit específico no repositório do GitHub (por exemplo, para testar recursos não lançados ou uma bifurcação), use a seguinte configuração:

- uses: snowflakedb/snowflake-cli-action@v2.0
  with:
    custom-github-ref: "feature/my-branch" # or a tag/commit hash
Copy

Você também pode incluir outros parâmetros de entrada.

Este recurso está disponível na versão snowflake-cli-action 1.6 ou posterior.

Configurar com segurança a ação em seu fluxo de trabalho de CI/CD

É possível configurar a ação no seu fluxos de trabalho CI/CD com segurança usando um dos seguintes métodos:

Usar a autenticação de federação de identidade de carga de trabalho (WIF) OpenID Connect (OIDC )

Nota

A autenticação WIF OIDC requer a versão 3.11.0 ou posterior do Snowflake CLI.

A autenticação WIF OIDC é uma maneira segura e moderna de autenticar com o Snowflake sem armazenar chaves privadas como segredos. Essa abordagem usa o OIDC (OpenID Connect) do GitHub para autenticar com o Snowflake.

Para configurar a autenticação WIF OIDC, siga estas etapas:

  1. Configurar WIF OIDC definindo um usuário de serviço com o tipo de identidade de carga de trabalho OIDC:

    CREATE USER <username>
TYPE = SERVICE
WORKLOAD_IDENTITY = (
  TYPE = OIDC
  ISSUER = 'https://token.actions.githubusercontent.com'
  SUBJECT = '<your_subject>'
)
    Copy

Nota

Por padrão, sua entidade deve ser parecida com repo:<repository-owner/repository-name>:environment:<environment>.

  • Para simplificar a geração da entidade, use o comando gh, em que <environment_name> é o ambiente definido nas configurações do repositório, conforme mostrado no exemplo a seguir:

gh repo view <repository-owner/repository-name> --json nameWithOwner | jq -r '"repo:\(.nameWithOwner):environment:<environment_name>"'
Copy

Para mais informações sobre a personalização do assunto, consulte a referência sobre OpenID Connect no GitHub.

  1. Armazene seu identificador de conta Snowflake em segredos do GitHub. Para obter mais informações, consulte a documentação de ações GitHub.

  2. Configure a ação Snowflake CLI em seu arquivo YAML de fluxo de trabalho do GitHub, conforme mostrado:

    name: Snowflake OIDC
on: [push]

permissions:
  id-token: write  # Required for OIDC token generation
  contents: read

jobs:
  oidc-job:
    runs-on: ubuntu-latest
    environment: test-env # this should match the environment used in the subject
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false
      - name: Set up Snowflake CLI
        uses: snowflakedb/snowflake-cli-action@v2.0
        with:
          use-oidc: true
          cli-version: "3.11"
      - name: test connection
        env:
          SNOWFLAKE_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}
        run: snow connection test -x
    Copy

    Para mais informações sobre a configuração da autenticação WIF OIDC para sua conta Snowflake e a configuração do provedor de OIDC do GitHub, consulte Federação de identidades de carga de trabalho.

Autenticação de chave privada

Para usar a autenticação de chave privada, você precisa armazenar sua chave privada do Snowflake nos segredos do GitHub e configurar a ação Snowflake CLI para usá-la.

  1. Armazene sua chave privada do Snowflake nos segredos do GitHub.

Para obter mais informações, consulte a documentação de ações GitHub.

  1. Configure a ação Snowflake CLI em seu arquivo YAML de fluxo de trabalho do GitHub, conforme mostrado:

    name: Snowflake Private Key
on: [push]

jobs:
  private-key-job:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false
      - name: Set up Snowflake CLI
        uses: snowflakedb/snowflake-cli-action@v2.0
    Copy

Definição de conexões

Você pode definir uma ação do GitHub para se conectar ao Snowflake com uma conexão temporária ou com uma conexão definida no seu arquivo de configuração. Para obter mais informações sobre o gerenciamento de conexões, consulte Gerenciando conexões Snowflake.

Use uma conexão temporária

Para obter mais informações sobre conexões temporárias, consulte Use uma conexão temporária.

Para configurar suas credenciais do Snowflake para uma conexão temporária, siga estas etapas:

  1. Mapeie os segredos para as variáveis de ambiente no seu fluxo de trabalho do GitHub, no formato SNOWFLAKE_<key>=<value>, conforme mostrado:

    env:
  SNOWFLAKE_PRIVATE_KEY_RAW: ${{ secrets.SNOWFLAKE_PRIVATE_KEY_RAW }}
  SNOWFLAKE_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}
    Copy

  2. Configure a ação do CLI do Snowflake.

    Se você usar a versão mais recente do Snowflake CLI, não será necessário incluir o parâmetro cli-version. O exemplo a seguir instrui a ação a usar especificamente a versão 3.11.0 do Snowflake CLI:

    - uses: snowflakedb/snowflake-cli-action@v2.0
  with:
    cli-version: "3.11.0"
    Copy

  3. Opcional: Se sua chave privada estiver criptografada, para definir uma senha, defina a variável de ambiente PRIVATE_KEY_PASSPHRASE para a frase secreta da chave privada. O Snowflake usa esta senha para descriptografar a chave privada. Por exemplo:

    - name: Execute Snowflake CLI command
  env:
    PRIVATE_KEY_PASSPHRASE: ${{ secrets.PASSPHARSE }}
    Copy

    Para usar uma senha em vez de uma chave privada, desfaça a definição da variável de ambiente SNOWFLAKE_AUTHENTICATOR e adicione a variável SNOWFLAKE_PASSWORD, como segue:

    - name: Execute Snowflake CLI command
  env:
    SNOWFLAKE_USER: ${{ secrets.SNOWFLAKE_USER }}
    SNOWFLAKE_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}
    SNOWFLAKE_PASSWORD: ${{ secrets.SNOWFLAKE_PASSWORD }}
    Copy

    Nota

    Para melhorar sua experiência ao usar uma senha e MFA, o Snowflake recomenda que você configure o cache de MFA.

    Para obter mais informações sobre a configuração de credenciais do Snowflake em variáveis de ambiente, consulte Use variáveis de ambiente para credenciais Snowflake e para obter informações sobre a definição de variáveis de ambiente no seu fluxo de trabalho de CI/CD do GitHub, consulte Definição de variáveis de ambiente para um único fluxo de trabalho.

  4. Adicione os comandos snow que você deseja executar com a conexão temporária, conforme mostrado:

    run: |
  snow --version
  snow connection test --temporary-connection
    Copy

O exemplo a seguir mostra um arquivo de amostra concluído <repo-name>/.github/workflows/my-workflow.yaml:

name: deploy
on: [push]

jobs:
  version:
    name: "Check Snowflake CLI version"
    runs-on: ubuntu-latest
    steps:
      # Snowflake CLI installation
      - uses: snowflakedb/snowflake-cli-action@v2.0

        # Use the CLI
      - name: Execute Snowflake CLI command
        env:
          SNOWFLAKE_AUTHENTICATOR: SNOWFLAKE_JWT
          SNOWFLAKE_USER: ${{ secrets.SNOWFLAKE_USER }}
          SNOWFLAKE_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}
          SNOWFLAKE_PRIVATE_KEY_RAW: ${{ secrets.SNOWFLAKE_PRIVATE_KEY_RAW }}
          PRIVATE_KEY_PASSPHRASE: ${{ secrets.PASSPHARSE }} # Passphrase is only necessary if private key is encrypted.
        run: |
          snow --help
          snow connection test -x
Copy

Depois de verificar se sua ação pode se conectar ao Snowflake com sucesso, você pode adicionar mais comandos do Snowflake CLI como snow notebook create ou snow git execute. Para obter informações sobre os comandos aceitos, consulte Referência de comando de Snowflake CLI.

Usar um arquivo de configuração

Para obter mais informações sobre a definição de conexões, consulte Definição de conexões.

Para configurar suas credenciais do Snowflake para uma conexão específica, siga estas etapas:

  1. Crie um arquivo config.toml na raiz do seu repositório Git com uma conexão de configuração vazia, conforme mostrado:

    default_connection_name = "myconnection"

[connections.myconnection]
    Copy

    Esse arquivo serve como um modelo e não deve conter credenciais reais.

  2. Mapeie os segredos para as variáveis de ambiente no seu fluxo de trabalho do GitHub, no formato SNOWFLAKE_<key>=<value>, conforme mostrado:

    env:
  SNOWFLAKE_CONNECTIONS_MYCONNECTION_PRIVATE_KEY_RAW: ${{ secrets.SNOWFLAKE_PRIVATE_KEY_RAW }}
  SNOWFLAKE_CONNECTIONS_MYCONNECTION_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}
    Copy

  3. Configure a ação do CLI do Snowflake.

    Se você usar a versão mais recente do Snowflake CLI, não será necessário incluir o parâmetro cli-version. O exemplo a seguir especifica uma versão desejada e o nome do arquivo de configuração padrão:

    - uses: snowflakedb/snowflake-cli-action@v2.0
  with:
    cli-version: "3.11.0"
    default-config-file-path: "config.toml"
    Copy

  4. Opcional: Se sua chave privada estiver criptografada, para definir uma senha, defina a variável de ambiente PRIVATE_KEY_PASSPHRASE para a frase secreta da chave privada. O Snowflake usa esta senha para descriptografar a chave privada. Por exemplo:

    - name: Execute Snowflake CLI command
  env:
    PRIVATE_KEY_PASSPHRASE: ${{ secrets.PASSPHARSE }}
    Copy

    Para usar uma senha em vez de uma chave privada, desfaça a definição da variável de ambiente SNOWFLAKE_AUTHENTICATOR e adicione a variável SNOWFLAKE_PASSWORD, como segue:

    - name: Execute Snowflake CLI command
  env:
    SNOWFLAKE_CONNECTIONS_MYCONNECTION_USER: ${{ secrets.SNOWFLAKE_USER }}
    SNOWFLAKE_CONNECTIONS_MYCONNECTION_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}
    SNOWFLAKE_CONNECTIONS_MYCONNECTION_PASSWORD: ${{ secrets.SNOWFLAKE_PASSWORD }}
    Copy

    Nota

    Para melhorar sua experiência ao usar uma senha e MFA, o Snowflake recomenda que você configure o cache de MFA.

  5. Adicione os comandos Snow que você deseja executar com uma conexão nomeada, conforme mostrado:

    run: |
  snow --version
  snow connection test
    Copy

O exemplo a seguir mostra um arquivo de amostra config.toml em seu repositório Git e um arquivo de amostra <repo-name>/.github/workflows/my-workflow.yaml concluído:

  • Arquivo config.toml de exemplo

    default_connection_name = "myconnection"

[connections.myconnection]
    Copy

  • Amostra de arquivo de fluxo de trabalho Git:

    name: deploy
on: [push]
jobs:
  version:
    name: "Check Snowflake CLI version"
    runs-on: ubuntu-latest
    steps:
      # Checkout step is necessary if you want to use a config file from your repo
      - name: Checkout repo
        uses: actions/checkout@v4
        with:
          persist-credentials: false

        # Snowflake CLI installation
      - uses: snowflakedb/snowflake-cli-action@v2.0
        with:
          default-config-file-path: "config.toml"

        # Use the CLI
      - name: Execute Snowflake CLI command
        env:
          SNOWFLAKE_CONNECTIONS_MYCONNECTION_AUTHENTICATOR: SNOWFLAKE_JWT
          SNOWFLAKE_CONNECTIONS_MYCONNECTION_USER: ${{ secrets.SNOWFLAKE_USER }}
          SNOWFLAKE_CONNECTIONS_MYCONNECTION_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}
          SNOWFLAKE_CONNECTIONS_MYCONNECTION_PRIVATE_KEY_RAW: ${{ secrets.SNOWFLAKE_PRIVATE_KEY_RAW }}
          PRIVATE_KEY_PASSPHRASE: ${{ secrets.PASSPHARSE }} #Passphrase is only necessary if private key is encrypted.
        run: |
          snow --help
          snow connection test
    Copy

Depois de verificar se sua ação pode se conectar ao Snowflake com sucesso, você pode adicionar mais comandos do Snowflake CLI como snow notebook create ou snow git execute. Para obter informações sobre os comandos aceitos, consulte Referência de comando de Snowflake CLI.

Linguagem: Português