Input and Access Types

Overview#

Resources in a component version are added using either an input type or an access type.

• Input type — embeds content by value. The content is stored alongside the component descriptor in the target repository.
• Access type — stores an access specification pointing to the content. In the constructor, this typically references an external location (e.g. an OCI registry) rather than embedding the content.

A resource must have exactly one of input or access. See the Component Constructor reference for the full YAML schema.

Input Types#

Dir/v1#

Embeds a directory as a tar archive.

resources:
- name: deploy-manifests
  type: blob
  input:
    type: Dir/v1
    path: ./deploy
    compress: true
    reproducible: true

File/v1#

Embeds a single file.

resources:
- name: config
  type: blob
  input:
    type: File/v1
    path: ./config.yaml
    mediaType: application/yaml

Embedding OCI Image Layouts#

The file/v1 input type can embed OCI image layout tar archives. When the media type is set to application/vnd.ocm.software.oci.layout.v1+tar, OCM recognizes the blob as a native OCI artifact and stores it as a proper OCI manifest during transfer to an OCI registry, making it accessible with standard OCI tooling.

resources:
- name: my-oci-artifact
  type: ociArtifact
  input:
    type: file/v1
    path: ./oci-artifact.tar
    mediaType: application/vnd.ocm.software.oci.layout.v1+tar

See the Working with OCI tutorial for a complete walkthrough.

Helm/v1#

Embeds a Helm chart from the local filesystem or a remote repository. Exactly one of path or helmRepository must be specified.

# Local chart
resources:
- name: my-chart
  type: helmChart
  input:
    type: Helm/v1
    path: ./charts/myapp
    repository: charts/myapp:1.0.0
---
# Remote chart (HTTP)
resources:
- name: ingress-chart
  type: helmChart
  input:
    type: Helm/v1
    helmRepository: https://github.com/kubernetes/ingress-nginx/releases/download/helm-chart-4.14.0/ingress-nginx-4.14.0.tgz
---
# Remote chart (OCI)
resources:
- name: podinfo-chart
  type: helmChart
  input:
    type: Helm/v1
    helmRepository: oci://ghcr.io/stefanprodan/charts/podinfo:6.9.1
    repository: charts/podinfo:6.9.1

UTF8/v1#

Embeds inline text or structured data. Exactly one of text, json, formattedJson, or yaml must be specified.

resources:
- name: config-data
  type: blob
  input:
    type: UTF8/v1
    json:
      replicas: 3
      env: production

Wget/v1#

Downloads content from an HTTP or HTTPS URL while the component version is constructed and embeds it as a local blob. Use it when the upstream artifact is a plain HTTP download (a release archive, a checksum file, a signed binary) and you want the bytes captured in the component version rather than fetched again at consumption time.

Alternative type names wget/v1, Wget, and wget are also accepted; Wget/v1 is canonical.

resources:
- name: release-archive
  type: blob
  version: 1.0.0
  input:
    type: Wget/v1
    url: https://downloads.example.com/myapp/1.0.0/myapp-linux-amd64.tar.gz
    mediaType: application/x-tar+gzip

With custom headers and a non-default verb:

resources:
- name: report
  type: blob
  version: 1.0.0
  input:
    type: Wget/v1
    url: https://api.example.com/reports
    verb: POST
    mediaType: application/json
    header:
      Accept:
        - application/json
      X-Request-Source:
        - ocm
    # base64 of {"format":"json"}
    body: eyJmb3JtYXQiOiJqc29uIn0=

See Tutorial: Work with HTTP Resources for media type resolution, redirects, download tuning, and credential configuration.

S3/v2#

Downloads a single object from an S3 or S3-compatible bucket while OCM constructs the component version, and stores it as a local blob. Use this input type when the content must travel with the component version. Two examples are an air-gapped delivery, and a bucket that the user of the component version cannot reach. The access type is the alternative: it leaves the object in the bucket and reads it on every download.

S3/v2 is the canonical type name. OCM also accepts s3/v2, S3 and s3. The fields are the same as the fields of the S3/v2 access type. You can therefore give the same object by value or by reference.

resources:
  - name: reference-dataset
    type: blob
    version: 1.0.0
    input:
      type: S3/v2
      region: eu-central-1
      bucketName: acme-artifacts
      objectKey: datasets/reference/1.0.0/reference.parquet
      mediaType: application/vnd.apache.parquet

For an S3-compatible store, set the endpoint and use path-style addressing:

resources:
  - name: reference-dataset
    type: blob
    version: 1.0.0
    input:
      type: S3/v2
      endpoint: https://minio.internal:9000
      usePathStyle: true
      bucketName: acme-artifacts
      objectKey: datasets/reference/1.0.0/reference.parquet

OCM streams the object to a file under the tempFolder of the filesystem.config.ocm.software/v1alpha1 configuration type. It does not hold the object in memory, so the size of the object does not change the memory use.

OCM v1 has no S3 input type.

Access Types#

OCIImage/v1#

References an OCI artifact (image or image index) in a registry. This is the canonical type name. The legacy aliases ociArtifact, ociRegistry, and ociImage are also accepted.

resources:
  - name: app-image
    type: ociImage
    version: 1.0.0
    relation: external
    access:
      type: OCIImage/v1
      imageReference: ghcr.io/acme/myapp:1.0.0

LocalBlob/v1#

References content stored alongside the component descriptor in the same repository. Legacy alias: localBlob. Typically created automatically when using input types or when transferring with --copy-resources.

When stored in an OCI registry, local blobs with OCI-native media types (e.g. application/vnd.oci.image.manifest.v1+json, application/vnd.oci.image.index.v1+json) are mapped to native OCI manifests and can be accessed directly by digest using standard OCI tools. The globalAccess field provides the native image reference for direct access. See the Working with OCI tutorial for details.

resources:
  - name: data
    type: blob
    relation: local
    access:
      type: LocalBlob/v1
      localReference: sha256:57563cb4a3e5c06a22c95aaa445...
      mediaType: application/octet-stream

OCIImageLayer/v1#

References a single blob (layer) in an OCI repository by digest. Legacy alias: ociBlob.

resources:
  - name: layer-data
    type: blob
    version: 1.0.0
    relation: external
    access:
      type: OCIImageLayer/v1
      ref: ghcr.io/acme/myapp
      digest: sha256:abc123...
      size: 1048576
      mediaType: application/octet-stream

Helm/v1#

References a Helm chart in a Helm chart repository or OCI registry. Legacy alias: helm.

resources:
  - name: mariadb-chart
    type: helmChart
    version: 12.2.7
    relation: external
    access:
      type: Helm/v1
      helmChart: mariadb:12.2.7
      helmRepository: https://charts.bitnami.com/bitnami

GitHub/v1#

References a commit of a GitHub repository, downloaded as a source archive via the GitHub REST API. Also usable unversioned as GitHub. Legacy aliases: github, github/v1, gitHub, gitHub/v1.

* At least one of commit or ref must be set. A resource may be authored with only a ref; its commit is pinned later during digest processing. A source is never pinned, so give it a commit.

resources:
  - name: my-source
    version: 1.0.0
    type: directoryTree
    relation: external
    access:
      type: GitHub/v1
      repoUrl: https://github.com/open-component-model/ocm
      commit: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

The same access works under sources:, where it stays a remote reference: sources carry no digest and no copy mode embeds them.

File/v1alpha1#

References a file by URI (RFC 8089). Legacy alias: file.

resources:
  - name: readme
    type: blob
    relation: external
    access:
      type: File/v1alpha1
      uri: file:///path/to/readme.md
      mediaType: text/markdown

Wget/v1#

References content served over HTTP or HTTPS. The bytes stay on the remote server and are fetched when the resource is downloaded, when its digest is computed, and when the component version is transferred.

Because the content is not under your control, the expected digest can be pinned on the resource itself, using the digest field alongside access rather than inside it. It is then verified on every fetch. See Tutorial: Work with HTTP Resources.

Alternative type names wget/v1, Wget, and wget are also accepted; Wget/v1 is canonical. The fields are identical to those of the Wget/v1 input type, so the same request can be expressed either by value or by reference.

resources:
  - name: release-archive
    type: blob
    version: 1.0.0
    relation: external
    access:
      type: Wget/v1
      url: https://downloads.example.com/myapp/1.0.0/myapp-linux-amd64.tar.gz
      mediaType: application/x-tar+gzip

For guidance on choosing between the input and the access type, and for media type resolution, redirects, download tuning, and credential configuration, see How-To: Add Resources from HTTP URLs.

S3/v2#

References a single object in an S3 or S3-compatible bucket. The content stays in the bucket. OCM reads it when it downloads the resource, and when it computes the digest of the resource. The type addresses one object, not a whole repository. It does not make S3 a component version repository.

S3/v2 is the canonical type name. OCM also accepts s3/v2, S3 and s3. These are the names of the OCM v1 s3 access type. Matching is exact, and S3/v1 and s3/v1 do not resolve. See Migrating from OCM v1.

resources:
  - name: reference-dataset
    type: blob
    version: 1.0.0
    relation: external
    access:
      type: S3/v2
      region: eu-central-1
      bucketName: acme-artifacts
      objectKey: datasets/reference/1.0.0/reference.parquet
      mediaType: application/vnd.apache.parquet

For an S3-compatible store, set the endpoint and use path-style addressing:

resources:
  - name: reference-dataset
    type: blob
    version: 1.0.0
    relation: external
    access:
      type: S3/v2
      endpoint: https://minio.internal:9000
      usePathStyle: true
      bucketName: acme-artifacts
      objectKey: datasets/reference/1.0.0/reference.parquet

Object versions and integrity#

Integrity comes from the OCM SHA-256 digest over the content, computed with the genericBlobDigest/v1 normalisation. OCM does not use the S3 ETag, because the ETag is not a whole-object hash for a multipart upload. If the resource already has a digest, OCM compares the computed digest with it. A difference fails the operation.

Digest processing also pins the access to the object version that it read, so a later read gets the same object. A pin is only possible if the object has a version:

• On a versioned bucket, OCM writes the reported versionId of the object into version. If the specification already sets version, OCM sends it with the request, and the response must return the same value.
• On an unversioned bucket, which is the AWS default, S3 reports the placeholder null. The placeholder does not change after an overwrite, so it pins nothing, and OCM never writes it into the specification. The resource digest still detects a replaced object, so verification fails. OCM does not accept the wrong content.

If you need reproducibility, enable bucket versioning, or set version.

Migrating from OCM v1#

S3/v2 is the v2 format of the OCM v1 s3 access type, plus the fields endpoint and usePathStyle. OCM v2 reads an access specification that OCM v1 wrote in the v2 format without changes.

OCM v2 does not read the OCM v1 v1 format, which uses other field names. s3/v1 and S3/v1 do not resolve. OCM v2 reads an unversioned s3 or S3 as v2, so a specification in the v1 format fails with bucketName is required. OCM v1 writes an unversioned s3 in the v1 format by default. Rename the fields of these specifications:

# OCM v1
access:
  type: s3
  region: eu-central-1
  bucket: acme-artifacts
  key: datasets/reference/1.0.0/reference.parquet
  mediaType: application/vnd.apache.parquet

# OCM v2
access:
  type: S3/v2
  region: eu-central-1
  bucketName: acme-artifacts
  objectKey: datasets/reference/1.0.0/reference.parquet
  mediaType: application/vnd.apache.parquet

Behavior. Both versions support download only. OCM v1 reached AWS S3 only. The fields endpoint and usePathStyle are new in OCM v2, and they make S3-compatible stores such as MinIO, Ceph and R2 usable. OCM v1 also reads S3/v2, but it ignores these two fields and reads from AWS S3. Integrity comes from the OCM SHA-256 digest over the content, in OCM v1 and in OCM v2. It does not come from the S3 ETag.

Credentials. The consumer identity type is S3 in both versions, but the attribute that holds the object location and the credential property names changed. See Credential Consumer Identities: Migrating from OCM v1.