> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Criar regra de cache de imagens
> Mapeia um prefixo da conta para um registry de origem. Use `prefix` igual a `hub`, `upstream_registry` igual a `docker.io` e `upstream_prefix` igual a `library` para obter `cr.sa-saopaulo-1.basaltic.cloud/my-account/hub/nginx:1.27`.
O cache reduz pulls repetidos e o consumo dos limites do Docker Hub por IP. Credenciais autenticadas podem aumentar esse limite. Criar a regra não copia imagens: repositórios e conteúdo são criados no primeiro pull sem cache.
Uma busca na origem exige `registry:BatchImportUpstreamImage` além das permissões de pull, pois consome armazenamento. Clientes com apenas pull recebem 404 quando a imagem não está em cache. O prefixo não pode conter repositórios preexistentes. Requer `registry:CreatePullThroughCacheRule`.
Exige a ação IAM **`registry:CreatePullThroughCacheRule`**. Veja [REGISTRY permissões](/pt/registry/permissions) para a lista completa, o escopo de cada ação e um exemplo de política.
## OpenAPI
````yaml /pt/api-reference/specs/registry.yaml post /v1/pull-through-cache-rules
openapi: 3.0.3
info:
title: API Basaltic Registry
version: 1.0.0
description: >-
Registry de imagens de contêiner. A API de gerenciamento usa
`registry..basaltic.sh`; Docker e clientes OCI usam
`cr..basaltic.cloud`. Esta referência descreve `/v1`, autenticado
por OAuth ou sessão do console. `/v2` segue a especificação OCI Distribution
1.1.
`POST /v1/authorization-token` gera uma senha para `docker login`, que a
troca por tokens por repositório em `/v2/token`. A senha dura 12 horas, mas
decisões de autorização usam as políticas atuais e tokens de cinco minutos.
Referências de imagem incluem o identificador da conta; use a `uri`
retornada pelo servidor.
Blobs e manifestos são imutáveis e identificados por SHA-256. Tags são
apontadores mutáveis, salvo com `tag_mutability: immutable`. Excluir por
digest remove manifesto e tags; excluir por tag preserva o manifesto.
Camadas são deduplicadas em toda a conta. `size_bytes` conta blobs
distintos, e a coleta em segundo plano libera os que nenhuma imagem ainda
usa.
Uma política de recurso permite acesso entre contas ou público. Acesso entre
contas exige autorização tanto no recurso como no IAM do chamador.
`kms_key` aceita UUID, nome na conta ou CRN de uma chave simétrica
habilitada na mesma conta e região. Referências inválidas retornam 400;
chaves inexistentes retornam 404. Respostas usam ResourceRef e preservam ID
e CRN sem nome quando a chave foi excluída.
contact:
name: Basaltic Support
email: ping@basaltic.sh
license:
name: Proprietary
url: https://basaltic.sh/terms
servers:
- url: https://registry.{region}.basaltic.sh
description: Endpoint de API regional
variables:
region:
default: sa-saopaulo-1
description: Código de região
security:
- BearerAuth: []
tags:
- name: Authorization
description: Credencial usada por `docker login`
- name: Repositories
description: Ciclo de vida, configurações, imagens e tags dos repositórios
- name: Policies
description: Políticas de recurso e de ciclo de vida
- name: Encryption
description: Criptografia de camadas em repouso
- name: Pull-through cache
description: Cache de imagens de outro registry no seu namespace
paths:
/v1/pull-through-cache-rules:
post:
tags:
- Pull-through cache
summary: Criar regra de cache de imagens
description: >-
Mapeia um prefixo da conta para um registry de origem. Use `prefix`
igual a `hub`, `upstream_registry` igual a `docker.io` e
`upstream_prefix` igual a `library` para obter
`cr.sa-saopaulo-1.basaltic.cloud/my-account/hub/nginx:1.27`.
O cache reduz pulls repetidos e o consumo dos limites do Docker Hub por
IP. Credenciais autenticadas podem aumentar esse limite. Criar a regra
não copia imagens: repositórios e conteúdo são criados no primeiro pull
sem cache.
Uma busca na origem exige `registry:BatchImportUpstreamImage` além das
permissões de pull, pois consome armazenamento. Clientes com apenas pull
recebem 404 quando a imagem não está em cache. O prefixo não pode conter
repositórios preexistentes. Requer
`registry:CreatePullThroughCacheRule`.
operationId: createPullThroughCacheRule
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePullThroughCacheRuleRequest'
responses:
'201':
description: Regra criada. Nenhum conteúdo foi buscado.
content:
application/json:
schema:
$ref: '#/components/schemas/PullThroughCacheRuleResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'409':
description: >-
O prefixo já pertence a outra regra ou contém um repositório
existente.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
$ref: '#/components/responses/UnprocessableEntity'
components:
parameters:
IdempotencyKey:
name: Idempotency-Key
in: header
description: >-
Chave opcional gerada pelo cliente que torna uma criação segura para
reprodução. A reintentar uma solicitação com a mesma chave retorna o
resultado original literalmente em vez de criar um recurso duplicado. A
reutilização de uma chave com um corpo de solicitação diferente é
rejeitada (422); uma solicitação cuja chave ainda está sendo processada
retorna 409. Os registros são honrados por 24 horas. Use um UUID ou
token exclusivo semelhante.
required: false
schema:
type: string
maxLength: 255
example: 550e8400-e29b-41d4-a716-446655440000
schemas:
CreatePullThroughCacheRuleRequest:
type: object
properties:
prefix:
type: string
description: >-
Um ou dois componentes minúsculos de nome de repositório. Formam o
início do caminho de todos os repositórios criados pela regra.
example: hub
upstream_registry:
type: string
description: >-
Hostname com porta opcional. O prefixo `https://` é aceito e
removido; outros esquemas são recusados porque a conexão pode
transportar credenciais.
example: docker.io
upstream_prefix:
type: string
description: Caminho opcional adicionado antes do nome na origem.
example: library
upstream_username:
type: string
description: >-
Opcional. Autenticar no Docker Hub pode aumentar os limites de pull
mesmo para imagens públicas.
upstream_secret:
type: string
format: password
description: >-
Senha ou token somente para escrita, criptografado em repouso e
nunca retornado. Obrigatório junto com `upstream_username`;
credenciais parciais são rejeitadas.
required:
- prefix
- upstream_registry
PullThroughCacheRuleResponse:
type: object
properties:
pull_through_cache_rule:
$ref: '#/components/schemas/PullThroughCacheRule'
required:
- pull_through_cache_rule
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
- request_id
properties:
code:
type: string
description: Código de erro identificando o tipo de erro
example: INVALID_INPUT
message:
type: string
description: Mensagem de erro legível pelo ser humano
example: Invalid request parameters
params:
type: object
additionalProperties: true
description: >-
Valores não sensíveis opcionais para interpolação de erros
localizados, codificados por código de erro. Nunca presente para
erros de servidor.
example:
instances: 2
pools: 0
request_id:
type: string
format: uuid
description: Solicitar ID para depuração
example: 550e8400-e29b-41d4-a716-446655440000
PullThroughCacheRule:
type: object
properties:
crn:
type: string
example: crn:registry:sa-saopaulo-1:my-account:pull-through-cache-rule/hub
prefix:
type: string
description: Componentes iniciais dos nomes dos repositórios associados à regra.
example: hub
uri_prefix:
type: string
description: >-
Prefixo de referência para pull produzido pela regra. Use o valor
retornado para preservar corretamente o namespace da conta.
example: cr.sa-saopaulo-1.basaltic.cloud/my-account/hub
upstream_registry:
type: string
description: >-
Host de origem. `docker.io` é armazenado como
`registry-1.docker.io`, que serve `/v2`, como faz o daemon Docker.
example: registry-1.docker.io
upstream_prefix:
type: string
description: >-
Adicionado antes do restante do nome na origem. `library` faz
`hub/nginx` resolver para `library/nginx` no Docker Hub.
example: library
upstream_username:
type: string
example: robot
has_credential:
type: boolean
description: >-
Indica se há segredo armazenado. O segredo nunca é retornado;
rotacionar exige escrever um novo valor.
example: true
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
required:
- crn
- prefix
- uri_prefix
- upstream_registry
- has_credential
- created_at
- updated_at
responses:
BadRequest:
description: Parâmetros de solicitação inválidos
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: INVALID_INPUT
message: Invalid request parameters
request_id: 550e8400-e29b-41d4-a716-446655440000
Unauthorized:
description: Autenticação necessária ou token inválido
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: UNAUTHORIZED
message: Authentication required
request_id: 550e8400-e29b-41d4-a716-446655440000
Forbidden:
description: Permissões insuficientes
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: ACCESS_DENIED
message: You don't have permission to perform this action
request_id: 550e8400-e29b-41d4-a716-446655440000
UnprocessableEntity:
description: >
A solicitação está bem formada, mas não pode ser processada conforme
enviada. Nas operações que aceitam `Idempotency-Key` este é o caso de
reutilização de chave: a chave foi vista pela primeira vez com uma carga
de solicitação diferente, então reproduzir o resultado armazenado
responderia a uma pergunta que o chamador não fez.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: IDEMPOTENCY_KEY_REUSED
message: >-
This Idempotency-Key was already used with a different request
payload
request_id: 550e8400-e29b-41d4-a716-446655440000
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >+
Um token bearer OAuth 2.0, enviado como `Authorization: Bearer `.
Esta é a forma recomendada de autenticação.
Obtenha o token trocando o par de chaves de acesso de uma conta de
serviço em `POST /v1/oauth/token` com `grant_type=client_credentials`.
Esse é o fluxo padrão de credenciais de cliente; bibliotecas compatíveis
com OAuth podem obter e renovar o token para você.
```
curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \
https://iam.basaltic.sh/v1/oauth/token
```
Os tokens duram uma hora por padrão. O mesmo par de chaves de acesso
também serve como credencial AWS SigV4 para o endpoint de objetos
compatível com S3, que aceita somente esse método de autenticação.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.