Esta página foi traduzida pela API Cloud Translation.

Restringir downloads de artefatos com regras de download

Nesta página, descrevemos como restringir downloads de artefatos dos seus repositórios do Artifact Registry criando e gerenciando regras de download.

Com as regras de download, é possível permitir ou negar downloads de artefatos dos seus repositórios e pacotes. Também é possível definir condições para que a regra seja aplicada a tags ou versões específicas.

Para detalhes sobre como as regras de download funcionam, consulte a seção Restringir downloads de artefatos da visão geral "Controlar o acesso e proteger artefatos".

Antes de começar

Se você ainda não tiver um, crie um repositório padrão no formato Docker.
(Opcional) Configure padrões para comandos da Google Cloud CLI.

Funções exigidas

Para receber as permissões necessárias para criar e gerenciar regras de download, peça ao administrador para conceder a você os seguintes papéis do IAM no repositório:

Criar, atualizar, receber, listar e excluir regras: Administrador do repositório do Artifact Registry (roles/artifactregistry.repoAdmin)
Receber e listar regras: Leitor do Artifact Registry (roles/artifactregistry.reader)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

Criar regras de download

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

RULE_NAME: o nome da regra. O nome precisa ser exclusivo no repositório, ter um comprimento máximo de 256 caracteres e consistir em caracteres alfanuméricos, caracteres codificados por porcentagem ou caracteres na lista [-, ., _, ~, :, @, +, ^].
ACTION: a ação aplicada a um download que corresponde a esta regra. Escolha entre ALLOW, em que a regra permite que downloads correspondentes ocorram, e DENY, em que a regra impede que downloads correspondentes ocorram.
PACKAGE: (opcional) o nome do pacote. Se fornecida, a regra será aplicada apenas ao pacote especificado, em vez de a todo o repositório.
CONDITION: (opcional) uma expressão CEL que define uma regra de correspondência. Se fornecida, aplica a regra apenas aos downloads que correspondem à condição especificada. Por exemplo, pkg.version.id < '3.0'.
PROJECT: o Google Cloud ID do projeto. Se o ID do projeto contiver dois pontos (:), consulte Projetos com escopo de domínio.
LOCATION: o local regional ou multirregional do repositório.
REPOSITORY: o ID do repositório.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud artifacts rules create RULE_NAME \
    --action=ACTION \
    --project=PROJECT \
    --location=LOCATION \
    --repository=REPOSITORY \
    --package=PACKAGE \
    --condition="CONDITION"

Windows (PowerShell)

gcloud artifacts rules create RULE_NAME `
    --action=ACTION `
    --project=PROJECT `
    --location=LOCATION `
    --repository=REPOSITORY `
    --package=PACKAGE `
    --condition="CONDITION"

Windows (cmd.exe)

gcloud artifacts rules create RULE_NAME ^
    --action=ACTION ^
    --project=PROJECT ^
    --location=LOCATION ^
    --repository=REPOSITORY ^
    --package=PACKAGE ^
    --condition="CONDITION"

Uma nova regra é criada com a seguinte saída:

Created rule [RULE_NAME].

Para mais informações, consulte o comando gcloud artifacts rules create.

API

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

RULE_NAME: o nome da regra. O nome precisa ser exclusivo no repositório, ter um comprimento máximo de 256 caracteres e consistir em caracteres alfanuméricos, caracteres codificados por porcentagem ou caracteres na lista [-, ., _, ~, :, @, +, ^].
ACTION: a ação aplicada a um download que corresponde a esta regra. Escolha entre ALLOW, em que a regra permite que downloads correspondentes ocorram, e DENY, em que a regra impede que downloads correspondentes ocorram.
PACKAGE: (opcional) o nome do pacote. Se fornecida, a regra será aplicada apenas ao pacote especificado, em vez de a todo o repositório.
CONDITION: (opcional) uma expressão CEL que define uma regra de correspondência. Se fornecida, aplica a regra apenas aos downloads que correspondem à condição especificada. Por exemplo, pkg.version.id < '3.0'.
PROJECT: o Google Cloud ID do projeto. Se o ID do projeto contiver dois pontos (:), consulte Projetos com escopo de domínio.
LOCATION: o local regional ou multirregional do repositório.
REPOSITORY: o ID do repositório.

Método HTTP e URL:

POST https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules?ruleID=RULE_NAME

Corpo JSON da solicitação:

{
  "action":"ACTION",
  "packageId":"PACKAGE",
  "condition":
  {
    "expression":"CONDITION"
  }
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d @request.json \
     "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules?ruleID=RULE_NAME"

PowerShell (Windows)

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json" `
    -InFile request.json `
    -Uri "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules?ruleID=RULE_NAME" | Select-Object -Expand Content

Uma nova regra é criada com a seguinte saída:

{
  "name": "projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME",
  "action": ACTION,
  "operation": "DOWNLOAD"
}

Para mais informações, consulte a referência REST.

Listar regras de download

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

PROJECT: o Google Cloud ID do projeto. Se o ID do projeto contiver dois pontos (:), consulte Projetos com escopo de domínio.
LOCATION: o local regional ou multirregional do repositório.
REPOSITORY: o nome do repositório.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud artifacts rules list \
    --project=PROJECT \
    --location=LOCATION \
    --repository=REPOSITORY

Windows (PowerShell)

gcloud artifacts rules list `
    --project=PROJECT `
    --location=LOCATION `
    --repository=REPOSITORY

Windows (cmd.exe)

gcloud artifacts rules list ^
    --project=PROJECT ^
    --location=LOCATION ^
    --repository=REPOSITORY

Uma lista de regras para o projeto, local e repositório especificados é exibida, semelhante a esta:

RULE: my-rule
PACKAGE: example.com/foo
ACTION: DENY
OPERATION: DOWNLOAD
CONDITION: pkg.version.id < '3.0'

Para mais informações, consulte o comando gcloud artifacts rules list.

API

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

PROJECT: o Google Cloud ID do projeto. Se o ID do projeto contiver dois pontos (:), consulte Projetos com escopo de domínio.
LOCATION: o local regional ou multirregional do repositório.
REPOSITORY: o nome do repositório.

Método HTTP e URL:

GET https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Execute o seguinte comando:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules"

PowerShell (Windows)

Execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules" | Select-Object -Expand Content

Uma lista de regras para o projeto, local e repositório especificados é exibida, semelhante a esta:

{
  "rules": [
    {
      "name": "projects/my-project/locations/us-central1/repositories/my-repo/rules/my-rule",
      "action": "DENY",
      "operation": "DOWNLOAD",
      "condition": {
        "expression": "pkg.version.id \u003c '3.0'"
      },
      "packageId": "example.com/foo"
    }
  ]
}

Para mais informações, consulte a referência REST.

Descrever regras de download

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

RULE_NAME: o nome da regra. O nome precisa ser exclusivo no repositório.
PROJECT: o Google Cloud ID do projeto. Se o ID do projeto contiver dois pontos (:), consulte Projetos com escopo de domínio.
LOCATION: o local regional ou multirregional do repositório.
REPOSITORY: o nome do repositório.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud artifacts rules describe RULE_NAME \
    --project=PROJECT \
    --location=LOCATION \
    --repository=REPOSITORY

Windows (PowerShell)

gcloud artifacts rules describe RULE_NAME `
    --project=PROJECT `
    --location=LOCATION `
    --repository=REPOSITORY

Windows (cmd.exe)

gcloud artifacts rules describe RULE_NAME ^
    --project=PROJECT ^
    --location=LOCATION ^
    --repository=REPOSITORY

Os detalhes da regra são exibidos de forma semelhante a esta:

RULE: my-rule
PACKAGE: example.com/foo
ACTION: DENY
OPERATION: DOWNLOAD
CONDITION: pkg.version.id < '3.0'

Para mais informações, consulte o comando gcloud artifacts rules describe.

API

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

RULE_NAME: o nome da regra. O nome precisa ser exclusivo no repositório.
PROJECT: o Google Cloud ID do projeto. Se o ID do projeto contiver dois pontos (:), consulte Projetos com escopo de domínio.
LOCATION: o local regional ou multirregional do repositório.
REPOSITORY: o nome do repositório.

Método HTTP e URL:

GET https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Execute o seguinte comando:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME"

PowerShell (Windows)

Execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME" | Select-Object -Expand Content

Os detalhes da regra são exibidos de forma semelhante a esta:

{
  "rules": [
    {
      "name": "projects/my-project/locations/us-central1/repositories/my-repo/rules/my-rule",
      "action": "DENY",
      "operation": "DOWNLOAD",
      "condition": {
        "expression": "pkg.version.id \u003c '3.0'"
      },
      "packageId": "example.com/foo"
    }
  ]
}

Para mais informações, consulte a referência REST.

Atualizar regras de download

gcloud

Remova as variáveis que você não quer atualizar.

Antes de usar os dados do comando abaixo, faça estas substituições:

RULE_NAME: o nome da regra. O nome precisa ser exclusivo no repositório.
ACTION: a ação aplicada a um download que corresponde a esta regra. Escolha entre ALLOW e DENY.
PACKAGE: o nome do pacote. Se não for fornecido, a regra será aplicada a todo o repositório.
CONDITION: uma expressão CEL que define uma regra de correspondência. Se fornecida, aplica a regra apenas aos downloads que correspondem à condição especificada. Por exemplo, pkg.version.id < '3.0'.
PROJECT: o Google Cloud ID do projeto. Se o ID do projeto contiver dois pontos (:), consulte Projetos com escopo de domínio.
LOCATION: o local regional ou multirregional do repositório.
REPOSITORY: o nome do repositório.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud artifacts rules update RULE_NAME \
    --action=ACTION \
    --project=PROJECT \
    --location=LOCATION \
    --repository=REPOSITORY \
    --package=PACKAGE \
    --condition="CONDITION"

Windows (PowerShell)

gcloud artifacts rules update RULE_NAME `
    --action=ACTION `
    --project=PROJECT `
    --location=LOCATION `
    --repository=REPOSITORY `
    --package=PACKAGE `
    --condition="CONDITION"

Windows (cmd.exe)

gcloud artifacts rules update RULE_NAME ^
    --action=ACTION ^
    --project=PROJECT ^
    --location=LOCATION ^
    --repository=REPOSITORY ^
    --package=PACKAGE ^
    --condition="CONDITION"

Os detalhes da regra atualizada são mostrados de maneira semelhante a esta:

Updated rule [RULE_NAME].
action: ACTION
condition:
  expression: CONDITION
name: projects/PROJECT/locationsLOCATION/repositories/REPOSITORY/rules/RULE_NAME
operation: DOWNLOAD

Para mais informações, consulte o comando gcloud artifacts rules update.

API

Remova as variáveis que você não quer atualizar.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

RULE_NAME: o nome da regra. O nome precisa ser exclusivo no repositório.
ACTION: a ação aplicada a um download que corresponde a esta regra. Escolha entre ALLOW e DENY.
PACKAGE: o nome do pacote. Se não for fornecido, a regra será aplicada a todo o repositório.
CONDITION: uma expressão CEL que define uma regra de correspondência. Se fornecida, aplica a regra apenas aos downloads que correspondem à condição especificada. Por exemplo, pkg.version.id < '3.0'.
PROJECT: o Google Cloud ID do projeto. Se o ID do projeto contiver dois pontos (:), consulte Projetos com escopo de domínio.
LOCATION: o local regional ou multirregional do repositório.
REPOSITORY: o nome do repositório.

Método HTTP e URL:

PATCH https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME

Corpo JSON da solicitação:

{
  "action":"ACTION",
  "packageId":"PACKAGE",
  "condition":
  {
    "expression":"CONDITION"
  }
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d @request.json \
     "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME"

PowerShell (Windows)

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json" `
    -InFile request.json `
    -Uri "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME" | Select-Object -Expand Content

Os detalhes atualizados da regra são mostrados de maneira semelhante a esta:

{
  "name": "projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME",
  "action": ACTION,
  "operation": "DOWNLOAD"
}

Para mais informações, consulte a referência REST.

Excluir regras de download

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

RULE_NAME: o nome da regra. O nome precisa ser exclusivo no repositório.
PROJECT: o Google Cloud ID do projeto. Se o ID do projeto contiver dois pontos (:), consulte Projetos com escopo de domínio.
LOCATION: o local regional ou multirregional do repositório.
REPOSITORY: o nome do repositório.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud artifacts rules delete RULE_NAME \
    --project=PROJECT \
    --location=LOCATION \
    --repository=REPOSITORY

Windows (PowerShell)

gcloud artifacts rules delete RULE_NAME `
    --project=PROJECT `
    --location=LOCATION `
    --repository=REPOSITORY

Windows (cmd.exe)

gcloud artifacts rules delete RULE_NAME ^
    --project=PROJECT ^
    --location=LOCATION ^
    --repository=REPOSITORY

A regra é excluída com a seguinte saída:

You are about to delete rule [RULE_NAME]

Do you want to continue (Y/n)?  Y

Deleted rule [RULE_NAME].

Para mais informações, consulte o comando gcloud artifacts rules delete.

API

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

RULE_NAME: o nome da regra. O nome precisa ser exclusivo no repositório.
PROJECT: o Google Cloud ID do projeto. Se o ID do projeto contiver dois pontos (:), consulte Projetos com escopo de domínio.
LOCATION: o local regional ou multirregional do repositório.
REPOSITORY: o nome do repositório.

Método HTTP e URL:

DELETE https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Execute o seguinte comando:

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME"

PowerShell (Windows)

Execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME" | Select-Object -Expand Content

Para mais informações, consulte a referência REST.

Usar a CEL para definir condições

É possível definir condições para suas regras de download com a Common Expression Language (CEL), uma linguagem de código aberto para avaliação de expressões. O Artifact Registry fornece o objeto pkg que contém os seguintes atributos:

pkg.id: uma string que representa o nome do pacote do artefato. Pode ser usado com regras definidas no nível do repositório.
pkg.version.id: uma string que representa a versão do artefato.
pkg.version.tag: uma string que representa a tag do artefato. Use somente em um repositório do Docker.

É possível usar operadores lógicos e funções integradas com a CEL. Confira alguns exemplos de expressões CEL que podem ser úteis nas suas regras de download:

Útil para regras definidas no nível do repositório:

  pkg.id == 'myPackage'  #Artifact package matches 'myPackage'
  pkg.id.startsWith('my') #Artifact package must start with 'my'

Útil para regras definidas em pacotes:

  pkg.version.id != '1.0.0' #Artifact version is not '1.0.0'
  pkg.version.id > '1.0.1' || pkg.version.id < '0.0.1' #Artifact version is greater than '1.0.1' or less than '0.0.1'
  pkg.version.id.startsWith('1.0.') #Artifact version must start with '1.0.'
  pkg.version.id in ['1.0.0', '1.2.0'] #Artifact version must be a member of the list ['1.0.0', '1.2.0']
  pkg.version.tag == 'tag1' #Artifact tag must be 'tag1'
  pkg.version.tag.startsWith('tag') #Artifact tag must start with 'tag'
  pkg.version.tag in ['tag1', 'tag2'] #Artifact tag must be a member of the list ['tag1', 'tag2']

Ao adicionar regras com condições baseadas em tags, como pkg.version.tag == 'latest', nos seus repositórios do Docker, lembre-se do seguinte:

Ao extrair por resumo, o cliente não fornece uma tag. As condições que usam tags serão correspondidas a uma tag vazia e poderão resultar em um comportamento inesperado.
Para imagens de contêiner de multiarquitetura, as condições que usam tags podem não funcionar como esperado e devem ser evitadas.

Restringir downloads de artefatos com regras de download Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Funções exigidas

Criar regras de download

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

API

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

Listar regras de download

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

API

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

Descrever regras de download

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

API

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

Atualizar regras de download

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

API

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

Excluir regras de download

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

API

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

Usar a CEL para definir condições

Restringir downloads de artefatos com regras de download