Quarkus ORAS

Integrate ORAS Java SDK Available for JDK and native build.

sunset.jpg][ORAS

Installation

If you want to use this extension, you need to add the io.quarkiverse.oras:quarkus-oras extension first to your build file.

For instance, with Maven, add the following dependency to your POM file:

<dependency>
    <groupId>io.quarkiverse.oras</groupId>
    <artifactId>quarkus-oras</artifactId>
    <version>0.0.4</version>
</dependency>

Usage

An land.oras.Registry is made available to your application as a CDI bean if configuration is found.

For example to use the Docker Hub registry (anonymous), you can add the following configuration to your application.properties file:

quarkus.oras.registries.dockerhub.enabled=true
quarkus.oras.registries.dockerhub.host=docker.io
package com.acme.oras;

import jakarta.enterprise.context.ApplicationScoped;
import io.quarkiverse.oras.runtime.OrasRegistry;
import land.oras.ContainerRef;
import land.oras.Registry;

@ApplicationScoped
public class MySampleService {

    @OrasRegistry("dockerhub")
    Registry dockerhub;

    public String getIndex() {
        return hub.getIndex(ContainerRef.parse("library/alpine:latest")).getJson();
    }

}

The extension supports OCI layouts. OCI layouts are a way to store artifacts in a local directory.

OCI layouts can be used to store artifacts in a local directory.

To control the location of OCI layouts, you can use the quarkus.oras.layouts.path property.

quarkus.oras.layouts.path=/var/storage/oci

On the Java side it’s possible to retrieve instance of and OCI layout using by injecting io.quarkiverse.oras.runtime.OrasLayouts:

package com.acme.oras;

import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.Response;

import org.jboss.resteasy.reactive.RestPath;
import io.quarkiverse.oras.runtime.OCILayouts;
import land.oras.LayoutRef;
import land.oras.OCILayout;

@Path("/v2")
@ApplicationScoped
public class MySampleResource {

    @Inject
    OCILayouts ociLayouts;

    @GET
    @Path("{name}/blobs/{digest}")
    public Response headBlob(@RestPath("name") String name, @RestPath String digest) {
        OCILayout ociLayout = ociLayouts.getLayout(name);
        LayoutRef layoutRef = LayoutRef.parse("%s@%s".formatted(ociLayout.getPath(), digest));
        return Response.ok(ociLayout.getBlob(layoutRef)).build();
    }
}

Extension Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

quarkus.oras.layouts.path

Path to storage

Environment variable: QUARKUS_ORAS_LAYOUTS_PATH

string

.

quarkus.oras.registries."names".enabled

An optional boolean to enable the registry client. Defaults to true

Environment variable: QUARKUS_ORAS_REGISTRIES__NAMES__ENABLED

boolean

true

quarkus.oras.registries."names".host

The registry default host

Environment variable: QUARKUS_ORAS_REGISTRIES__NAMES__HOST

string

required

quarkus.oras.registries."names".username

The registry username

Environment variable: QUARKUS_ORAS_REGISTRIES__NAMES__USERNAME

string

quarkus.oras.registries."names".password

The registry password

Environment variable: QUARKUS_ORAS_REGISTRIES__NAMES__PASSWORD

string

quarkus.oras.registries."names".secure

An optional boolean to enable secure connection. Defaults to true

Environment variable: QUARKUS_ORAS_REGISTRIES__NAMES__SECURE

boolean

true