Create an artifact deployment record

POST

/orgs/{org}/artifacts/metadata/deployment-record

Create or update deployment records for an artifact associated with an organization. This endpoint allows you to record information about a specific artifact, such as its name, digest, environments, cluster, and deployment. The deployment name has to be uniqe within a cluster (i.e a combination of logical, physical environment and cluster) as it identifies unique deployment. Multiple requests for the same combination of logical, physical environment, cluster and deployment name will only create one record, successive request will update the existing record. This allows for a stable tracking of a deployment where the actual deployed artifact can change over time.

API method documentation

Parameters

Path Parameters

org

required

string

The organization name. The name is not case sensitive.

Request Body ^required

Media type application/json

object

name

required

The name of the artifact.

string

>= 1 characters <= 256 characters

digest

required

The hex encoded digest of the artifact.

string

>= 71 characters <= 71 characters /^sha256:[a-f0-9]{64}$/

version

The artifact version.

string

>= 1 characters <= 100 characters

status

required

The status of the artifact. Can be either deployed or decommissioned.

string

Allowed values: deployed decommissioned

logical_environment

required

The stage of the deployment.

string

>= 1 characters <= 128 characters

physical_environment

The physical region of the deployment.

string

<= 128 characters

cluster

The deployment cluster.

string

<= 128 characters

deployment_name

required

The unique identifier for the deployment represented by the new record. To accommodate differing containers and namespaces within a cluster, the following format is recommended: {namespaceName}-{deploymentName}-{containerName}.

string

<= 256 characters

tags

The tags associated with the deployment.

object

<= 5 properties

key

additional properties

string

runtime_risks

A list of runtime risks associated with the deployment.

Array<string>

<= 4 items unique items

Allowed values: critical-resource internet-exposed lateral-movement sensitive-data

github_repository

The name of the GitHub repository associated with the artifact. This should be used when there are no provenance attestations available for the artifact. The repository must belong to the organization specified in the path parameter.

If a provenance attestation is available for the artifact, the API will use the repository information from the attestation instead of this parameter.

string

>= 1 characters <= 100 characters /^[A-Za-z0-9.\-_]+$/

return_records

If true, the endpoint will return the created or updated record in the response body.

boolean

default: true

Examples

Example default

{
  "name": "awesome-image",
  "digest": "sha256:1bb1e949e55dcefc6353e7b36c8897d2a107d8e8dca49d4e3c0ea8493fc0bc72",
  "status": "deployed",
  "logical_environment": "prod",
  "physical_environment": "pacific-east",
  "cluster": "moda-1",
  "deployment_name": "deployment-pod",
  "tags": {
    "data-access": "sensitive"
  }
}

Responses

200

Artifact deployment record stored successfully.

Media type application/json

object

total_count

required

The number of deployment records created

integer

deployment_records

Array<object>

Artifact Deployment Record

Artifact Metadata Deployment Record

object

id

integer

digest

string

logical_environment

string

physical_environment

string

cluster

string

deployment_name

string

tags

object

key

additional properties

string

runtime_risks

A list of runtime risks associated with the deployment.

Array<string>

<= 4 items unique items

Allowed values: critical-resource internet-exposed lateral-movement sensitive-data

created_at

string

updated_at

string

attestation_id

The ID of the provenance attestation associated with the deployment record.

integer

nullable

Examples

Example default

{
  "total_count": 1,
  "deployment_records": [
    {
      "id": 123,
      "digest": "sha256:1bb1e949e55dcefc6353e7b36c8897d2a107d8e8dca49d4e3c0ea8493fc0bc72",
      "logical_environment": "prod",
      "physical_environment": "pacific-east",
      "cluster": "moda-1",
      "deployment_name": "prod-deployment",
      "tags": {
        "data": "sensitive"
      },
      "created": "2011-01-26T19:14:43Z",
      "updated_at": "2011-01-26T19:14:43Z",
      "attestation_id": 456
    }
  ]
}

403

Forbidden

Media type application/json

Basic Error

Basic Error

object

message

string

documentation_url

string

url

string

status

string

Example ^generated

{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}

404

Resource not found

Media type application/json

Basic Error

Basic Error

object

message

string

documentation_url

string

url

string

status

string

Example ^generated

{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}