Usar cqlsh para se conectar ao Amazon Keyspaces

Para se conectar ao Amazon Keyspaces usando cqlsh, você pode usar o cqlsh-expansion. Este é um kit de ferramentas que contém ferramentas comuns do Apache Cassandra, como cqlsh, e auxiliares pré-configurados para o Amazon Keyspaces, mantendo total compatibilidade com o Apache Cassandra. O cqlsh-expansion integra o plug-in de autenticação SigV4 e permite que você se conecte usando chaves de acesso do IAM em vez de nome de usuário e senha. Você só precisa instalar os scripts cqlsh para fazer uma conexão e não a distribuição completa do Apache Cassandra, porque o Amazon Keyspaces é uma tecnologia sem servidor. Esse pacote de instalação leve inclui os cqlsh-expansion e os scripts clássicos cqlsh que você pode instalar em qualquer plataforma compatível com Python.

Para obter informações gerais sobre o cqlsh, consulte cqlsh: shell do CQL.

Usar a cqlsh-expansion para se conectar ao Amazon Keyspaces

Instalar e configurar a cqlsh-expansion

1. Para instalar o pacote cqlsh-expansion Python, você pode executar um comando pip. Isso instala os scripts cqlsh-expansion em sua máquina usando uma instalação pip e um arquivo contendo uma lista de dependências. O --user flag instrui pip a usar o diretório de instalação do usuário do Python para sua plataforma. Em um sistema baseado em Unix, esse deve ser o diretório ~/.local/.

   Você precisa do Python 3 para instalar o cqlsh-expansion. Para descobrir sua versão do Python, use Python --version. Para instalar, você pode executar o seguinte comando.

   python3 -m pip install --user cqlsh-expansion

   A saída deve ser semelhante a esta.

   Collecting cqlsh-expansion
     Downloading cqlsh_expansion-0.9.6-py3-none-any.whl (153 kB)
        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 153.7/153.7 KB 3.3 MB/s eta 0:00:00
   Collecting cassandra-driver
     Downloading cassandra_driver-3.28.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (19.1 MB)
        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 19.1/19.1 MB 44.5 MB/s eta 0:00:00
   Requirement already satisfied: six>=1.12.0 in /usr/lib/python3/dist-packages (from cqlsh-expansion) (1.16.0)
   Collecting boto3
     Downloading boto3-1.29.2-py3-none-any.whl (135 kB)
        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 135.8/135.8 KB 17.2 MB/s eta 0:00:00
   Collecting cassandra-sigv4>=4.0.2
     Downloading cassandra_sigv4-4.0.2-py2.py3-none-any.whl (9.8 kB)
   Collecting botocore<1.33.0,>=1.32.2
     Downloading botocore-1.32.2-py3-none-any.whl (11.4 MB)
        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 11.4/11.4 MB 60.9 MB/s eta 0:00:00
   Collecting s3transfer<0.8.0,>=0.7.0
     Downloading s3transfer-0.7.0-py3-none-any.whl (79 kB)
        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 79.8/79.8 KB 13.1 MB/s eta 0:00:00
   Collecting jmespath<2.0.0,>=0.7.1
     Downloading jmespath-1.0.1-py3-none-any.whl (20 kB)
   Collecting geomet<0.3,>=0.1
     Downloading geomet-0.2.1.post1-py3-none-any.whl (18 kB)
   Collecting python-dateutil<3.0.0,>=2.1
     Downloading python_dateutil-2.8.2-py2.py3-none-any.whl (247 kB)
        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 247.7/247.7 KB 33.1 MB/s eta 0:00:00
   Requirement already satisfied: urllib3<2.1,>=1.25.4 in /usr/lib/python3/dist-packages (from botocore<1.33.0,>=1.32.2->boto3->cqlsh-expansion) (1.26.5)
   Requirement already satisfied: click in /usr/lib/python3/dist-packages (from geomet<0.3,>=0.1->cassandra-driver->cqlsh-expansion) (8.0.3)
   Installing collected packages: python-dateutil, jmespath, geomet, cassandra-driver, botocore, s3transfer, boto3, cassandra-sigv4, cqlsh-expansion
     WARNING: The script geomet is installed in '/home/ubuntu/.local/bin' which is not on PATH.
     Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
     WARNING: The scripts cqlsh, cqlsh-expansion and cqlsh-expansion.init are installed in '/home/ubuntu/.local/bin' which is not on PATH.
     Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
   Successfully installed boto3-1.29.2 botocore-1.32.2 cassandra-driver-3.28.0 cassandra-sigv4-4.0.2 cqlsh-expansion-0.9.6 geomet-0.2.1.post1 jmespath-1.0.1 python-dateutil-2.8.2 s3transfer-0.7.0

   Se o diretório de instalação não estiver noPATH, você precisará adicioná-lo seguindo as instruções do seu sistema operacional. Abaixo está um exemplo para o Ubuntu Linux.

   export PATH="$PATH:/home/ubuntu/.local/bin"

   Para confirmar se o pacote está instalado, você pode executar o comando a seguir.

   cqlsh-expansion --version

   A saída deve ser algo parecido com isso.

   cqlsh 6.1.0

2. Para configurar o cqlsh-expansion, você pode executar um script de pós-instalação para concluir automaticamente as seguintes etapas:

   1. Crie o diretório .cassandra no diretório inicial do usuário se ele ainda não existir.

   2. Copie um arquivo cqlshrc de configuração pré-configurado no diretório .cassandra.

   3. Copie o certificado digital Starfield no diretório .cassandra. O Amazon Keyspaces usa esse certificado para configurar a conexão segura com o Transport Layer Security (TLS). A criptografia em trânsito fornece uma camada adicional de proteção de dados ao criptografar seus dados à medida que eles viajam de e para o Amazon Keyspaces.

   Para revisar o script primeiro, você pode acessá-lo no repositório do Github em post_install.py.

   Para usar o script, você pode executar o seguinte comando.

   cqlsh-expansion.init

   nota

   O diretório e o arquivo criados pelo script de pós-instalação não são removidos quando você desinstala o cqlsh-expansion usando pip uninstall, e precisam ser excluídos manualmente.

Conectar-se ao Amazon Keyspaces usando cqlsh-expansion

1. Configure seu Região da AWS e adicione-o como uma variável de ambiente do usuário.

   Para adicionar sua região padrão como uma variável de ambiente em um sistema baseado em Unix, você pode executar o comando a seguir. Para este exemplo, usamos Leste dos EUA (Norte da Virgínia).

   export AWS_DEFAULT_REGION=us-east-1

   Para obter mais informações sobre como definir variáveis de ambiente, inclusive para outras plataformas, consulte Como definir variáveis de ambiente.

2. Encontre seu endpoint.

   Escolha o endpoint de serviço apropriado para sua região. Para analisar os endpoints disponíveis para o Amazon Keyspaces, consulte Endpoints de serviço para Amazon Keyspaces. Para este exemplo, usamos o endpoint cassandra.us-east-1.amazonaws.com.

3. Configurar o modo de autenticação.

   A conexão com as chaves de acesso do IAM (usuários, perfis e identidades federadas do IAM) é o método recomendado para aumentar a segurança.

   Antes de se conectar com as chaves de acesso do IAM, você precisa concluir as seguintes etapas:

   1. Crie um usuário do IAM ou siga as melhores práticas e crie um perfil do IAM que os usuários do IAM possam assumir. Para obter mais informações sobre como criar uma chave de acesso do IAM, consulte Como criar e configurar AWS credenciais para o Amazon Keyspaces.

   2. Crie uma política do IAM que conceda ao perfil (ou ao usuário do IAM) no mínimo o acesso somente leitura ao Amazon Keyspaces. Para obter mais informações sobre as permissões necessárias para que o usuário ou o perfil do IAM se conecte ao Amazon Keyspaces, consulte Como acessar as tabelas do Amazon Keyspaces.

   3. Adicione as chaves de acesso do usuário do IAM às variáveis de ambiente do usuário, conforme mostrado no exemplo a seguir.

      export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
      export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

      Para obter mais informações sobre como definir variáveis de ambiente, inclusive para outras plataformas, consulte Como definir variáveis de ambiente.

      nota

      Se você estiver se conectando a partir de uma instância do Amazon EC2, também precisará configurar uma regra de saída no grupo de segurança que permita o tráfego da instância para o Amazon Keyspaces. Para obter mais informações sobre como visualizar e editar regras de saída do EC2, consulte Adicionar regras a um grupo de segurança no Guia do usuário do Amazon EC2.

4. Conectar-se ao Amazon Keyspaces usando a cqlsh-expansion e a autenticação SigV4.

   Para se conectar ao Amazon Keyspaces com a cqlsh-expansion, você pode usar o comando a seguir. Certifique-se de substituir o endpoint de serviço pelo endpoint correto para sua região.

   cqlsh-expansion cassandra.us-east-1.amazonaws.com 9142 --ssl

   Se a conexão for bem-sucedida, você verá um resultado semelhante a este:

   Connected to Amazon Keyspaces at cassandra.us-east-1.amazonaws.com:9142
   [cqlsh 6.1.0 | Cassandra 3.11.2 | CQL spec 3.4.4 | Native protocol v4]
   Use HELP for help.
   cqlsh current consistency level is ONE.
   cqlsh>

   Se você encontrar um erro de conexão, consulte Não consigo me conectar ao Amazon Keyspaces com o cqlsh para obter informações sobre solução de problemas.

   • Conectar-se ao Amazon Keyspaces com credenciais específicas do serviço.

     Para se conectar à combinação tradicional de nome de usuário e senha que o Cassandra usa para autenticação, você deve primeiro criar credenciais específicas do serviço para o Amazon Keyspaces, conforme descrito em Gerar credenciais específicas do serviço. Você também precisa conceder a esse usuário permissões para acessar o Amazon Keyspaces. Para obter mais informações, consulte Como acessar as tabelas do Amazon Keyspaces.

     Depois de criar credenciais e permissões específicas do serviço para o usuário, você deve atualizar o arquivo cqlshrc, normalmente encontrado no caminho do diretório do usuário ~/.cassandra/. No arquivo cqlshrc, vá para a seção [authentication] do Cassandra e comente o módulo e a classe SigV4 em [auth_provider] usando o caractere “;”, conforme mostrado no exemplo a seguir.

     [auth_provider]
     
     ; module = cassandra_sigv4.auth
     
     ; classname = SigV4AuthProvider

     Depois de atualizar o arquivo cqlshrc, você pode se conectar ao Amazon Keyspaces com credenciais específicas do serviço usando o comando a seguir.

     cqlsh-expansion cassandra.us-east-1.amazonaws.com 9142 -u myUserName -p myPassword --ssl

Limpeza

• Para remover o pacote cqlsh-expansion, é possível usar o comando pip uninstall.

  pip3 uninstall cqlsh-expansion

  O comando pip3 uninstall não remove o diretório e os arquivos relacionados criados pelo script de pós-instalação. Para remover a pasta e os arquivos criados pelo script de pós-instalação, você pode excluir o diretório .cassandra.

Como configurar manualmente as conexões cqlsh para o TLS

O Amazon Keyspaces só aceita conexões seguras usando Transport Layer Security (TLS). Você pode usar o utilitário cqlsh-expansion que baixa automaticamente o certificado para você e instala um arquivo cqlshrc de configuração pré-configurado. Para obter mais informações sobre isso, consulte Usar a cqlsh-expansion para se conectar ao Amazon Keyspaces nesta página.

Se quiser baixar o certificado e configurar a conexão manualmente, você pode fazer isso usando as etapas a seguir.

1. Faça o download do certificado digital Starfield usando o comando a seguir e salve sf-class2-root.crt localmente ou em seu diretório inicial.

   curl https://certs.secureserver.net/repository/sf-class2-root.crt -O

   nota

   Você também pode usar o certificado digital da Amazon para se conectar ao Amazon Keyspaces e continuar fazendo isso se seu cliente estiver se conectando ao Amazon Keyspaces com sucesso. O certificado Starfield fornece compatibilidade adicional com versões anteriores para clientes que usam autoridades de certificação mais antigas.

2. Abra o arquivo cqlshrc de configuração no diretório inicial do Cassandra, por exemplo, ${HOME}/.cassandra/cqlshrc, e adicione as linhas a seguir.

   [connection]
   port = 9142
   factory = cqlshlib.ssl.ssl_transport_factory
   
   [ssl]
   validate = true
   certfile =  path_to_file/sf-class2-root.crt