Gerenciamento de segredos e configuração do app Streamlit

Os apps Streamlit geralmente precisam acessar informações confidenciais, como chaves deAPI, senhas e outras credenciais. A forma como você gerencia segredos no app Streamlit depende do ambiente de tempo de execução que você usa. O Streamlit in Snowflake oferece mecanismos seguros e integrados para acessar segredos nos tempos de execução tanto de warehouse quanto de contêiner. Para configuração do Streamlit, cada tempo de execução também tem restrições diferentes.

Na biblioteca Streamlit, os apps usam um diretório .streamlit/ para armazenar configurações e segredos:

  • .streamlit/config.toml: personaliza as configurações do app, como tema, layout e comportamento do servidor.

  • .streamlit/secrets.toml: armazena informações confidenciais, como chaves de API e credenciais (em desenvolvimento local).

O Streamlit in Snowflake oferece suporte a esses arquivos com algumas limitações, dependendo do seu ambiente de tempo de execução. A tabela a seguir resume o suporte para esses arquivos nos tempos de execução de warehouse e contêiner:

Recurso

Tempo de execução de warehouse

Tempo de execução de contêiner

Suporte para config.toml

Subconjunto limitado de opções de configuração

Subconjunto mais amplo de opções de configuração

Suporte para secrets.toml

Sem suporte

Com suporte, mas recomendado somente para variáveis de ambiente não secretas

Para secrets.toml, o Streamlit in Snowflake fornece um sistema de gerenciamento de segredos integrado mais seguro, recomendado para o gerenciamento de informações confidenciais. As seções a seguir descrevem como usar os segredos do Snowflake em seus apps.

Gerenciamento da conexão com o Snowflake

Para gerenciar sua conexão com o Snowflake, você pode usar st.connection("snowflake"). Isso permite que você se conecte ao Snowflake do seu ambiente de desenvolvimento local e do seu app implantado.

import streamlit as st

conn = st.connection("snowflake")
session = conn.session()

session.sql("SELECT 1").collect()

Nos tempos de execução de warehouse, você também pode usar a função get_active_session() do Snowpark para obter a sessão ativa.

import streamlit as st
from snowflake.snowpark.context import get_active_session

# ONLY IN WAREHOUSE RUNTIMES
session = get_active_session()
session.sql("SELECT 1").collect()

Importante

get_active_session() não é thread-safe e não pode ser usado em tempos de execução de contêiner.

Segredos em tempos de execução de contêiner

Você pode usar st.secrets para acessar segredos do Snowflake em seus apps Streamlit in Snowflake no tempo de execução de contêiner. Dessa forma, você pode armazenar e recuperar com segurança informações confidenciais, como chaves de API, credenciais e outros valores de configuração. Assim como o Streamlit faz com o .streamlit/secrets.toml em desenvolvimento local, o Streamlit in Snowflake também preenche os segredos para variáveis de ambiente.

Nota

Os tempos de execução de contêiner não têm acesso ao módulo _snowflake. Se você estiver migrando um app de tempo de execução de warehouse mais antigo que usa funções secretas _snowflake, substitua essas chamadas por st.secrets conforme descrito nesta seção.

Acesso a um segredo em um tempo de execução de contêiner

  1. Prepare o seguinte arquivo Python em``@my_stage/app_folder/streamlit_app.py``. Para obter informações sobre a preparação de arquivos, consulte Preparação de arquivos usando o Snowsight.

    import streamlit as st

secret_value = st.secrets["my_secret_name"]

  2. Crie um segredo em sua conta Snowflake:

    CREATE OR REPLACE SECRET my_secret
  TYPE = GENERIC_STRING
  SECRET_STRING = 'my_secret_value';

    Para obter mais informações, consulte CREATE SECRET.

  3. Crie uma integração de acesso externo (External Access Integration, EAI) e atribua o segredo a ela:

    CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION my_eai
  ALLOWED_AUTHENTICATION_SECRETS = (my_secret)
  ENABLED = TRUE;

  4. Crie seu app Streamlit para fazer referência ao segredo usando o parâmetro SECRETS:

    CREATE STREAMLIT my_container_app
  FROM '@my_stage/app_folder'
  MAIN_FILE = 'streamlit_app.py'
  RUNTIME_NAME = 'SYSTEM$ST_CONTAINER_RUNTIME_PY3_11'
  COMPUTE_POOL = my_compute_pool
  QUERY_WAREHOUSE = my_warehouse
  EXTERNAL_ACCESS_INTEGRATIONS = (my_eai)
  SECRETS = ('my_secret_name' = my_secret);

ALTER STREAMLIT my_container_app ADD LIVE VERSION FROM LAST;

    Nota

    Você deve atribuir a EAI e o segredo ao objeto Streamlit. Não é possível atribuir apenas o segredo a um objeto Streamlit.

    Como o segredo de cadeia de caracteres genérica my_secret está associado à cadeia de caracteres "my_secret_name" no parâmetro SECRETS, você pode acessar o segredo no código do app Streamlit usando st.secrets["my_secret_name"].

Tipos de segredo e variáveis de ambiente compatíveis

Os tempos de execução de contêiner são compatíveis com a cadeia de caracteres genérica e os segredos de autenticação básica. Além de mapear segredos para st.secrets, o Streamlit in Snowflake mapeia segredos para variáveis de ambiente. Os nomes das variáveis de ambiente diferenciam maiúsculas de minúsculas. Para segredos de autenticação básica, duas variáveis de ambiente são criadas: uma para o nome de usuário (sufixo _USERNAME) e outra para a senha (sufixo _PASSWORD).

Tipo de segredo

Acesso para st.secrets

Acesso para variável de ambiente

Cadeia de caracteres genérica

st.secrets["my_secret_name"]

os.environ["my_secret_name"]

Autenticação básica (nome de usuário)

st.secrets["my_secret_name"]["username"]

os.environ["my_secret_name_USERNAME"]

Autenticação básica (senha)

st.secrets["my_secret_name"]["password"]

os.environ["my_secret_name_PASSWORD"]

Nota

Provedor de nuvem, chave simétrica e tipos de segredo OAuth não são compatíveis no momento.

Segredos de cadeia de caracteres genérica

Os segredos de cadeia de caracteres genérica são armazenados como chaves de nível superior em st.secrets:

ALTER STREAMLIT my_container_app
  SET SECRETS = ('my_generic_secret_name' = my_generic_secret);

Você pode acessar o segredo usando a notação de dicionário ou de atributo:

import streamlit as st

api_key = st.secrets["my_generic_secret_name"]
api_key = st.secrets.my_generic_secret_name

Segredos de autenticação básica

Os segredos de autenticação básica são armazenados como objetos semelhantes a dict com os atributos "username" e "password":

ALTER STREAMLIT my_container_app
  SET SECRETS = ('my_basic_auth_secret_name' = my_basic_auth_secret);

Você pode acessar o segredo usando a notação de dicionário ou de atributo:

import streamlit as st

username = st.secrets["my_basic_auth_secret_name"]["username"]
password = st.secrets["my_basic_auth_secret_name"]["password"]

username = st.secrets.my_basic_auth_secret_name.username
password = st.secrets.my_basic_auth_secret_name.password

Segredos para repositórios de pacotes autenticados

Os segredos são automaticamente expostos como variáveis de ambiente. Em particular, isso permite a autenticação com repositórios de pacotes privados, como JFrog Artifactory.

Para a maioria dos repositórios de pacotes autenticados, use um segredo de autenticação básica. O segredo é convertido automaticamente em variáveis de ambiente com sufixos _USERNAME e _PASSWORD. Se você precisar de uma convenção de nomenclatura diferente, use segredos de cadeia de caracteres genérica e defina o nome de cada variável de ambiente manualmente. Para obter mais informações sobre as variáveis de ambiente que o uv usa, consulte Índices de pacotes (em inglês) na documentação do uv.

Exemplo: Autenticar em um repositório privado JFrog Artifactory

  1. Prepare os arquivos de origem do seu app em @my_stage/app_folder. Os arquivos de origem do seu app devem incluir um arquivo pyproject.toml que configura o índice de pacotes privados na tabela [[tool.uv.index]]:

    [[tool.uv.index]]
name = "my_jfrog_repo"
url = "https://my-org.jfrog.io/artifactory/api/pypi/pypi-local/simple"

    Para obter mais informações sobre como declarar as dependências do seu app em um arquivo pyproject.toml, consulte Gerenciamento de dependências para o app Streamlit.

  2. Crie um segredo de autenticação básica com as credenciais do JFrog:

    CREATE OR REPLACE SECRET jfrog_creds
  TYPE = PASSWORD
  USERNAME = 'my_username'
  PASSWORD = 'my_api_token';

  3. Crie uma integração de acesso externo para seu repositório privado:

    CREATE OR REPLACE NETWORK RULE jfrog_network_rule
  TYPE = HOST_PORT
  MODE = EGRESS
  VALUE_LIST = ('my-org.jfrog.io');

CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION jfrog_eai
  ALLOWED_NETWORK_RULES = (jfrog_network_rule)
  ALLOWED_AUTHENTICATION_SECRETS = (jfrog_creds)
  ENABLED = TRUE;

    Nota

    Para evitar um erro de DNS, talvez seja necessário incluir o provedor de nuvem do seu repositório na lista de valores da regra de rede. Por exemplo, se o repositório está na AWS, você pode precisar da seguinte lista de valores em sua regra de rede:

    VALUE_LIST = ('my-org.jfrog.io', '<jfrog-server-name>.s3.amazonaws.com');

  4. Anexe a EAI e o segredo ao seu app Streamlit:

    CREATE STREAMLIT my_app
  FROM '@my_stage/app_folder'
  MAIN_FILE = 'streamlit_app.py'
  RUNTIME_NAME = 'SYSTEM$ST_CONTAINER_RUNTIME_PY3_11'
  COMPUTE_POOL = my_compute_pool
  QUERY_WAREHOUSE = my_warehouse
  EXTERNAL_ACCESS_INTEGRATIONS = (jfrog_eai)
  SECRETS = ('UV_INDEX_MY_JFROG_REPO' = jfrog_creds);

ALTER STREAMLIT my_app ADD LIVE VERSION FROM LAST;

    Como o segredo de autenticação básica jfrog_creds está associado à cadeia de caracteres "UV_INDEX_MY_JFROG_REPO" no parâmetro SECRETS, o tempo de execução injeta automaticamente as variáveis de ambiente UV_INDEX_MY_JFROG_REPO_USERNAME e UV_INDEX_MY_JFROG_REPO_PASSWORD conforme exigido pelo uv.

Precedência de um arquivo .streamlit/secrets.toml local

Você pode combinar segredos gerenciados pelo Snowflake com uma arquivo .streamlit/secrets.toml local no diretório de origem do seu app. Quando ambos estão presentes, a biblioteca Streamlit os mescla. O arquivo .streamlit/secrets.toml definido localmente tem precedência sobre os segredos gerenciados pelo Snowflake.

Como o .streamlit/secrets.toml é armazenado como texto simples em seus arquivos preparados, não é uma prática recomendada de segurança armazenar segredos reais nele. Use o gerenciamento de segredos interno do Snowflake para credenciais confidenciais. Use o arquivo .streamlit/secrets.toml definido localmente para armazenar valores de configuração não confidenciais ou configurações específicas do ambiente.

Remover ou alterar os segredos do seu app Streamlit

  • Para remover todos os segredos de um app Streamlit in Snowflake, use a cláusula UNSET SECRETS com ALTER STREAMLIT:

    ALTER STREAMLIT my_database.my_schema.my_app
  UNSET SECRETS;

    Isso remove todas as associações de segredo do app Streamlit in Snowflake. Os objetos de segredo subjacentes permanecem em sua conta Snowflake e podem ser reatribuídos no futuro. Para remover também qualquer associação de EAI, remova a definição da propriedade EXTERNAL_ACCESS_INTEGRATIONS.

  • Para atualizar ou modificar os segredos que são anexados, use ALTER STREAMLIT com SET SECRETS:

    ALTER STREAMLIT my_database.my_schema.my_app
  SET SECRETS = ('new_secret' = my_new_secret);

Exemplo: Criar um app Streamlit de tempo de execução de contêiner com uma API externa autenticada

Este exemplo demonstra a criação de um app Streamlit in Snowflake que chama uma API externa usando uma chave de API de segredo.

  1. Prepare o seguinte arquivo Python em @my_stage/weather_app/streamlit_app.py:

    import streamlit as st
import requests

api_key = st.secrets["weather_api_name"]

response = requests.get(
    "https://api.weather.com/v1/current",
    headers={"Authorization": f"Bearer {api_key}"}
)

st.write(response.json())

    Como requests é uma dependência do streamlit, ele é incluído na imagem base do tempo de execução. Portanto, o tempo de execução o instala automaticamente, mesmo que você não inclua um arquivo de dependências ou configure um índice de pacotes.

  2. Crie o segredo, a regra de rede e a EAI:

    CREATE OR REPLACE SECRET weather_api_key
  TYPE = GENERIC_STRING
  SECRET_STRING = 'secret_value';

CREATE OR REPLACE NETWORK RULE weather_api_rule
  TYPE = HOST_PORT
  MODE = EGRESS
  VALUE_LIST = ('api.weather.com');

CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION weather_eai
  ALLOWED_NETWORK_RULES = (weather_api_rule)
  ALLOWED_AUTHENTICATION_SECRETS = (weather_api_key)
  ENABLED = TRUE;

  3. Crie o objeto Streamlit:

    CREATE STREAMLIT weather_app
  FROM '@my_stage/weather_app'
  MAIN_FILE = 'streamlit_app.py'
  RUNTIME_NAME = 'SYSTEM$ST_CONTAINER_RUNTIME_PY3_11'
  COMPUTE_POOL = my_compute_pool
  QUERY_WAREHOUSE = my_warehouse
  EXTERNAL_ACCESS_INTEGRATIONS = (weather_eai)
  SECRETS = ('weather_api_name' = weather_api_key);

ALTER STREAMLIT weather_app ADD LIVE VERSION FROM LAST;

Chamada de um Cortex Agent em tempo de execução de contêiner

Para chamar um Cortex Agent em um app de tempo de execução de contêiner, leia o token de sessão do contêiner Snowpark Container Services subjacente e use a biblioteca requests. Esse é o procedimento substituto recomendado para _snowflake.send_snow_api_request().

import requests
import json
import os

SNOWFLAKE_HOST = os.getenv("SNOWFLAKE_HOST")
SNOWFLAKE_ACCOUNT = os.getenv("SNOWFLAKE_ACCOUNT")
ANALYST_ENDPOINT = "/api/v2/cortex/analyst/message"
URL = "https://" + SNOWFLAKE_HOST + ANALYST_ENDPOINT

def get_token() -> str:
    """Read the oauth token embedded into SPCS container"""
    return open("/snowflake/session/token", "r").read()

def send_request(semantic_model_file, prompt):
    """Sends the prompt using the semantic model file """
    headers = {
        "Content-Type": "application/json",
        "accept": "application/json",
        "Authorization": f"Bearer {get_token()}",
        "X-Snowflake-Authorization-Token-Type": "OAUTH"
    }
    request_body = {
        "messages": [
            {
                "role": "user",
                "content": [{"type": "text", "text": prompt}],
            }
        ],
        "semantic_model_file": semantic_model_file,
    }
    return requests.post(URL, headers=headers, data=json.dumps(request_body))

Segredos em tempos de execução de warehouse

Em tempos de execução de warehouse, você pode usar o módulo _snowflake para acessar segredos diretamente no código do app Streamlit. Os tempos de execução de warehouse herdam o acesso ao módulo _snowflake dos procedimentos armazenados, o que permite recuperar segredos referenciados no objeto Streamlit.

Para usar segredos em um tempo de execução de warehouse:

  1. Crie um objeto de segredo no Snowflake. Para obter mais informações, consulte CREATE SECRET.

    CREATE OR REPLACE SECRET my_secret
  TYPE = GENERIC_STRING
  SECRET_STRING = 'my_secret_value';

  2. Crie uma integração de acesso externo e atribua o segredo a ela.

    CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION my_eai
  ALLOWED_AUTHENTICATION_SECRETS = (my_secret)
  ENABLED = TRUE;

  3. Faça referência ao segredo em seu objeto Streamlit usando o parâmetro SECRETS:

    ALTER STREAMLIT my_warehouse_app
  SET EXTERNAL_ACCESS_INTEGRATIONS = (my_eai)
  SECRETS = ('my_secret_key' = my_secret);

    Você deve atribuir a integração de acesso externo e o segredo ao objeto Streamlit. Não é possível atribuir apenas o segredo a um objeto Streamlit.

  4. No código do app Streamlit, importe o módulo _snowflake e recupere o segredo:

    import streamlit as st
import _snowflake

# Retrieve an API key from a generic string secret
my_secret = _snowflake.get_generic_secret_string('my_secret_key')

Para obter mais informações sobre como acessar segredos com o módulo _snowflake, consulte API de Python para acesso secreto.

Configuração do Streamlit

Os apps Streamlit podem incluir um arquivo de configuração (.streamlit/config.toml). Esse arquivo permite que você personalize vários aspectos do seu app, como tema, layout e comportamento. O arquivo de configuração é escrito no formato TOML. Para obter mais informações sobre as opções de configuração disponíveis, consulte a documentação do Streamlit em config.toml.

O suporte para opções de configuração varia de acordo com o ambiente de tempo de execução. Os tempos de execução de contêiner geralmente oferecem suporte mais amplo para opções de configuração do que os tempos de execução de warehouse, em especial para serviços estáticos. A tabela a seguir mostra quais seções de configuração são compatíveis com os tempos de execução de warehouse e de contêiner:

Seção de configuração

Tempo de execução de warehouse

Tempo de execução de contêiner

[global]

Sem suporte

Suporte limitado (disableWidgetStateDuplicationWarning)

[logger]

Sem suporte

Sem suporte

[client]

Sem suporte

Suporte limitado (showErrorDetails, showSidebarNavigation)

[runner]

Sem suporte

Com suporte

[server]

Sem suporte

Sem suporte

[browser]

Sem suporte

Sem suporte

[mapbox]

Sem suporte

Com suporte (obsoleto, use variáveis de ambiente em vez disso)

[theme]

Com suporte

Com suporte

[theme.sidebar]

Com suporte

Com suporte

[secrets]

Sem suporte

Com suporte (mas recomendado apenas para variáveis de ambiente não secretas)

[snowflake.sleep]

Com suporte

Não aplicável

Para obter informações sobre como usar a seção [snowflake.sleep] para configurar temporizadores de suspensão em tempos de execução de warehouse, consulte Temporizador de sono personalizado para um aplicativo Streamlit.

A estrutura de diretório a seguir mostra um exemplo de um app Streamlit com um arquivo de configuração:

source_directory/
├── .streamlit/
│   └── config.toml
├── pyproject.toml
├── streamlit_app.py
└── uv.lock