Skip to content

Create a pull-through cache rule

Images pulled from /// are fetched from the upstream on first pull, with the credentials in credentialSecret, and stored in the project. Checked as registry.cacheRules.create on the rule's prospective resource name. The secret needs a grant to the rule (consumer registry, consumerResource the rule's resourceName, version latest), made by the caller in Secrets. 409 conflict when the prefix is another rule's, still being deleted, or a live repository's scope, and when the project has 25 rules.

POST
https://registry-api.ezghcloud.com/v1/organizations/{orgId}/projects/{projectId}/pull-through-cache-rules

Authorization

  • apiKeyoptionalHTTP
  • oauthoptionalHTTP
  • sessionCookieoptionalAPI key in cookie

Path parameters

  • orgIdstringrequired

    UUID or prefixed ID (org_…)

  • projectIdstringrequired

    UUID or prefixed ID (prj_…)

Header parameters

  • Idempotency-Keyoptionalstring

    Makes a retry safe: the same key and request get the stored response.

    pattern: ^[\x21-\x7e]{1,200}$

Request bodyJSONrequired

  • credentialSecretstringrequired

    The resource name of a Secrets secret in the organization, with fields username and accessToken (a Docker Hub access token).

  • prefixstringrequired

    One lowercase path component, at most 30 bytes, fixed at creation. Images are pulled at ///.

    maxLength: 30, pattern: ^[a-z0-9]+((\.|_|__|-+)[a-z0-9]+)*$
  • upstreamdocker-hubrequired
  • descriptionoptionalstring
    maxLength: 1024
  • tagsoptionalmap ofstring

    At most 50; keys 1-128 characters, values at most 256, keys starting with ezgh: are reserved.

Returns

201

The rule, created.

JSON
  • createdAtstringrequired
    format: date-time
  • credentialSecretstringrequired

    The resource name of a Secrets secret in the organization, with fields username and accessToken (a Docker Hub access token).

  • descriptionstringrequired
  • idstringrequired
    format: uuid
  • lastFailureAtstring | nullrequired

    When a fill or tag recheck last failed, or null.

    format: date-time
  • organizationIdstringrequired
    format: uuid
  • prefixstringrequired

    One lowercase path component, at most 30 bytes, fixed at creation. Images are pulled at ///.

    maxLength: 30, pattern: ^[a-z0-9]+((\.|_|__|-+)[a-z0-9]+)*$
  • projectIdstringrequired
    format: uuid
  • regionstringrequired
  • resourceNamestringrequired

    ezgh::::.

  • slugstringrequired
  • statusstringrequired

    active, or deleting while its repositories are deleted; clients treat others as unknown.

  • tagsmap ofstringrequired

    At most 50; keys 1-128 characters, values at most 256, keys starting with ezgh: are reserved.

  • updatedAtstringrequired
    format: date-time
  • upstreamstringrequired

    The upstream registry: docker-hub (registry-1.docker.io). Clients treat others as unknown.

400

invalid_request (with issues), invalid_cursor, or the endpoint's own 400 codes.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

401

unauthenticated: no credential, or one that doesn't check out.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

403

access_denied: the caller's policies don't allow the action; forbidden_origin: a cookie-authenticated write from an origin that isn't allowed; spend_limit_reached.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

404

not_found: unknown, malformed, or in an organization the caller isn't in.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

409

quota_exceeded (an allocation quota, with quota), idempotency_conflict, idempotency_in_progress (with Retry-After), organization_deletion_pending, operation_in_progress, or the endpoint's own 409 codes.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

413

payload_too_large: the body is over the endpoint's limit (1 MiB unless it says otherwise).

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

429

too_many_requests, with Retry-After; or quota_exceeded (a rate, usage or concurrency quota, with quota), never with Retry-After.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

500

internal_error: a bug; the details are in the logs, under the request ID.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

503

unavailable: a dependency the request needs is down. Retry after Retry-After.

JSON
  • errorobjectrequired
    4 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • issuesoptionalarray ofobject

      invalid_request: one entry per problem, at a dotted path.

      2 properties
      • messagestringrequired
      • pathstringrequired
    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close