Skip to content

Container registry

Blocks run from container images. Whenever a block is created or scales up, its instances' images are pulled from a container registry. AIGr.id lets anyone run a container registry, on a cluster in the network or elsewhere, and list it in a network-wide container registry index so others can find and use it.

At a glance

Index service: containers-registry-svc on the management cluster (NodePort 30109).
Requirement: the registry must be OCI-compliant, for example Docker's registry:2.
External registries (Docker Hub, cloud registries, ...) can also be listed.

How it fits

  1. Someone runs a container registry and lists it in the index.
  2. Developers push their AIOS instance images to one or more registries.
  3. They reference those images in a component (containerRegistryInfo), and register the component.
  4. When a block is created from the component, its instances pull the image.

Deploy your own registry

From the repository root:

cd v1_deploy/container-registry

kubectl create ns registry      # namespace
kubectl create -f pv.yaml       # persistent volume
kubectl create -f pvc.yaml      # persistent volume claim
kubectl create -f deployment.yaml
kubectl create -f svc.yaml      # service

Edit the files to change storage, ports and so on. By default the service is exposed on NodePort 32633.

docker run --rm -d --name="registry" -p "5000:5000" registry:2

You don't have to use registry:2. Any registry that fully implements the OCI specification works.

List it in the index

1. Describe the registry (entry.json):

{
  "container_registry_id": "b3c38f52-8f2e-43a3-9aa9-bd9a4c75e509",
  "container_registry_name": "internal-ai-registry",
  "container_registry_metadata": {
    "environment": "production",
    "owner": "mlops-team",
    "region": "us-west-2"
  },
  "container_registry_tags": ["ai", "training", "internal", "fast-pull"],
  "container_registry_public_url": "http://10.13.21.22:32633",
  "container_registry_image_prefix": "10.13.21.22:32633",
  "container_registry_config": {
    "auth_required": true,
    "mirror_enabled": false,
    "storage_backend": "s3",
    "max_layer_size_mb": 500
  },
  "container_registry_storage_info": {
    "storage_type": "s3",
    "storage_size": -1,
    "memory_size": 8192,
    "registry_type": "aios"
  }
}

2. Register it:

curl -X POST http://<registry-db-url>/container_registry \
     -H "Content-Type: application/json" \
     -d @entry.json

Schema

@dataclass
class ContainerRegistry:
    # Unique ID (auto-generated UUID)
    container_registry_id: str = field(default_factory=lambda: str(uuid.uuid4()))

    # Human-readable name
    container_registry_name: str = ''

    # Free-form details (environment, owner, labels, ...)
    container_registry_metadata: Dict[str, Any] = field(default_factory=dict)

    # Tags for search and filtering
    container_registry_tags: List[str] = field(default_factory=list)

    # Public URL of the registry (e.g., http://registry.example.com)
    container_registry_public_url: str = ''

    # Image name prefix, e.g. registry.example.com in registry.example.com/my-image:v1
    container_registry_image_prefix: str = ''

    # Registry configuration (authentication, mirrors, endpoints, ...)
    container_registry_config: Dict[str, Any] = field(default_factory=dict)

    # Storage information:
    # {
    #     "storage_type": str      # "s3", "object-store", "fs", or "unknown"
    #     "storage_size": int      # in MB, or -1 for unlimited
    #     "memory_size": int       # in MB, or -1 if unknown or unlimited
    #     "registry_type": str     # "aios" for a registry run in the network, "external" for third-party
    # }
    container_registry_storage_info: Dict[str, Any] = field(default_factory=dict)

APIs

Endpoint Method What it does
/container_registry POST List a registry.
/container_registry/<registry_id> GET Get a registry's entry.
/container_registry/<registry_id> PUT Update fields (MongoDB-style update).
/container_registry/<registry_id> DELETE Remove a registry from the index.
/container_registries POST Search registries with a MongoDB-style filter.
/check_container_health/<registry_id> GET Check that the registry's public URL is reachable.
# List
curl -X POST http://<registry-db-url>/container_registry \
     -H "Content-Type: application/json" \
     -d @entry.json

# Get
curl -X GET http://<registry-db-url>/container_registry/<registry_id>

# Update
curl -X PUT http://<registry-db-url>/container_registry/<registry_id> \
     -H "Content-Type: application/json" \
     -d '{ "$set": {"container_registry_name": "updated-name"}}'

# Delete
curl -X DELETE http://<registry-db-url>/container_registry/<registry_id>

# Search
curl -X POST http://<registry-db-url>/container_registries \
     -H "Content-Type: application/json" \
     -d '{"container_registry_tags": {"$in": ["ai", "internal"]}}'

# Health check
curl -X GET http://<registry-db-url>/check_container_health/<registry_id>