Docker Registry

Discovery

Discover and manage container images, repositories, and registries in your Devgraph knowledge graph.

Overview

The Docker Registry molecule connects to Docker registries to discover container images, repositories, and manifests. It supports multiple registry types including Docker Hub, AWS ECR, Google GCR, Azure ACR, GitHub Container Registry (GHCR), and private registries.

Key Features:

• Discover registries, repositories, images, and manifests
• Support for multiple registry types
• Filter repositories and tags with regex patterns
• Track image metadata, layers, and vulnerabilities
• Limit tags per repository to manage API usage

Quick Start

providers:
  - name: docker-hub
    type: docker
    every: 300
    config:
      namespace: default
      registry_type: docker-hub
      api_url: https://registry-1.docker.io
      username: ${DOCKER_USERNAME}
      password: ${DOCKER_PASSWORD}
      selectors:
        - namespace_pattern: "library"
          repository_pattern: "^(nginx|redis)$"
          max_tags: 5

Configuration

Docker Hub

providers:
  - name: docker-hub
    type: docker
    every: 300
    config:
      namespace: default
      registry_type: docker-hub
      api_url: https://registry-1.docker.io
      username: ${DOCKER_USERNAME}
      password: ${DOCKER_PASSWORD}
      selectors:
        - namespace_pattern: "myorg"
          repository_pattern: ".*"
          max_tags: 10

AWS ECR

providers:
  - name: aws-ecr
    type: docker
    every: 300
    config:
      namespace: default
      registry_type: ecr
      api_url: https://123456789.dkr.ecr.us-west-2.amazonaws.com
      token: ${AWS_ECR_TOKEN}
      selectors:
        - namespace_pattern: "production"
          repository_pattern: ".*api.*"

Google GCR

providers:
  - name: google-gcr
    type: docker
    every: 300
    config:
      namespace: default
      registry_type: gcr
      api_url: https://gcr.io
      token: ${GCR_TOKEN}
      selectors:
        - namespace_pattern: "my-project"
          repository_pattern: ".*"

Azure ACR

providers:
  - name: azure-acr
    type: docker
    every: 300
    config:
      namespace: default
      registry_type: acr
      api_url: https://myregistry.azurecr.io
      username: ${ACR_USERNAME}
      password: ${ACR_PASSWORD}
      selectors:
        - namespace_pattern: "production"
          repository_pattern: ".*"

GitHub Container Registry (GHCR)

providers:
  - name: github-packages
    type: docker
    every: 300
    config:
      namespace: default
      registry_type: ghcr
      api_url: https://ghcr.io
      username: ${GITHUB_USERNAME}
      token: ${GITHUB_TOKEN}  # Classic PAT with read:packages
      selectors:
        # GHCR requires explicit repository names
        - namespace_pattern: "myorg"
          repository_pattern: "^(app-frontend|app-backend)$"
          max_tags: 10

Important for GHCR:

• Must use Classic Personal Access Token (not fine-grained)
• Required scope: read:packages
• Must specify exact repository names (no catalog discovery)
• Pattern like: ^(repo1|repo2|repo3)$

Private Registry

providers:
  - name: private-registry
    type: docker
    every: 300
    config:
      namespace: default
      registry_type: private
      api_url: https://registry.company.com
      username: ${REGISTRY_USERNAME}
      password: ${REGISTRY_PASSWORD}
      selectors:
        - namespace_pattern: "company.*"
          repository_pattern: ".*"

Configuration Options

Option	Type	Required	Default	Description
namespace	string	No	default	Namespace for created entities
api_url	string	No	https://registry-1.docker.io	Registry API base URL
registry_type	string	No	docker-hub	Registry type
username	string	No	-	Username for basic authentication
password	string	No	-	Password for basic authentication
token	string	No	-	Registry authentication token
timeout	integer	No	30	Request timeout in seconds
discover_vulnerabilities	boolean	No	false	Discover vulnerability data
selectors	list	No	[{}]	Repository selection criteria

Registry Types: docker-hub, ecr, gcr, acr, ghcr, private

Selector Options

Option	Type	Required	Default	Description
namespace_pattern	string	No	.*	Regex pattern for namespaces
repository_pattern	string	No	.*	Regex pattern for repository names
include_tags	list	No	-	Specific tags to include
exclude_tags	list	No	-	Tag patterns to exclude
max_tags	integer	No	10	Max tags per repository

Authentication

Docker Hub

1. Go to Docker Hub Security Settings
2. Create access token
3. Use username and token as password

AWS ECR

aws ecr get-login-password --region us-west-2

Google GCR

gcloud auth print-access-token

GitHub GHCR

1. Go to GitHub Tokens (Classic)
2. Generate token with read:packages scope
3. Use GitHub username and token

Entities Created

DockerRegistry

Represents a Docker registry instance.

Entity Structure:

apiVersion: entities.devgraph.ai/v1
kind: DockerRegistry
metadata:
  name: docker-hub
  namespace: default
  labels:
    devgraph.ai/registry-type: docker-hub
spec:
  name: Docker Hub
  registry_type: docker-hub
  url: https://registry-1.docker.io
  public: true

DockerRepository

Represents a container image repository.

Entity Structure:

apiVersion: entities.devgraph.ai/v1
kind: DockerRepository
metadata:
  name: nginx
  namespace: default
  labels:
    devgraph.ai/repository-name: nginx
spec:
  name: nginx
  full_name: library/nginx
  namespace: library
  description: Official NGINX image
  official: true
  star_count: 15000
  pull_count: 1000000000
  registry_url: https://registry-1.docker.io

DockerImage

Represents a specific tagged image version.

Entity Structure:

apiVersion: entities.devgraph.ai/v1
kind: DockerImage
metadata:
  name: nginx-latest
  namespace: default
  labels:
    devgraph.ai/image-tag: latest
spec:
  repository: nginx
  tag: latest
  digest: sha256:abc123...
  size: 142000000
  architecture: amd64
  os: linux
  created: "2024-01-15T10:00:00Z"
  layers: 7
  registry_url: https://registry-1.docker.io

DockerManifest

Represents image manifest metadata.

Entity Structure:

apiVersion: entities.devgraph.ai/v1
kind: DockerManifest
metadata:
  name: nginx-manifest-abc123
  namespace: default
spec:
  repository: nginx
  digest: sha256:abc123...
  media_type: application/vnd.docker.distribution.manifest.v2+json
  schema_version: 2
  architecture: amd64
  os: linux
  size: 142000000

Relationships

BELONGS_TO (Repository → Registry)

Repositories belong to registries.

DockerRepository --BELONGS_TO--> DockerRegistry

BELONGS_TO (Image → Repository)

Images belong to repositories.

DockerImage --BELONGS_TO--> DockerRepository

USES (Image → Manifest)

Images reference manifests.

DockerImage --USES--> DockerManifest

BELONGS_TO (Manifest → Repository)

Manifests belong to repositories.

DockerManifest --BELONGS_TO--> DockerRepository

Filtering Examples

Match Specific Repositories

selectors:
  - namespace_pattern: "myorg"
    repository_pattern: "^(api|worker|frontend)$"
    max_tags: 5

Exclude Patterns

selectors:
  - namespace_pattern: ".*"
    repository_pattern: ".*"
    exclude_tags: [".*-rc.*", ".*-beta.*", ".*-dev.*"]
    max_tags: 10

Include Specific Tags

selectors:
  - namespace_pattern: "production"
    repository_pattern: ".*"
    include_tags: ["latest", "stable", "v1.0.0"]

Official Docker Images

selectors:
  - namespace_pattern: "library"
    repository_pattern: "^(nginx|redis|postgres|mysql)$"
    max_tags: 3

Use Cases

Container Inventory Management

selectors:
  - namespace_pattern: "mycompany.*"
    repository_pattern: ".*"
    max_tags: 5

Multi-Registry Discovery

# Docker Hub
- name: docker-hub
  type: docker
  config:
    registry_type: docker-hub

# AWS ECR
- name: aws-ecr
  type: docker
  config:
    registry_type: ecr
    api_url: https://123456789.dkr.ecr.us-west-2.amazonaws.com

Production Images Only

selectors:
  - namespace_pattern: "production"
    repository_pattern: ".*"
    include_tags: ["latest", "stable"]
    exclude_tags: [".*-dev.*", ".*-test.*"]

Troubleshooting

Authentication Issues

Symptom: "401 Unauthorized" or "403 Forbidden"

Solutions:

1. Verify credentials are correct
2. Check token/password hasn't expired
3. For Docker Hub: Use access token, not account password
4. For GHCR: Use Classic PAT with read:packages scope

GHCR 403 Errors

Symptom: "403 Forbidden" when accessing GHCR

Solutions:

1. Use Classic Personal Access Token (not fine-grained)
2. Token must have read:packages scope
3. Verify package visibility (public or private with access)
4. Test authentication:

echo $GITHUB_TOKEN | docker login ghcr.io -u $GITHUB_USERNAME --password-stdin

GHCR Catalog Discovery Issues

Symptom: "403 Client Error: Forbidden for url: https://ghcr.io/v2/_catalog"

Solution: GHCR doesn't support catalog endpoint. Must specify exact repositories:

selectors:
  - namespace_pattern: "myorg"
    repository_pattern: "^(repo1|repo2|repo3)$"  # Explicit names

Rate Limiting

Symptom: "429 Too Many Requests"

Solutions:

1. Increase reconciliation interval
2. Reduce max_tags per repository
3. Use authentication for higher limits
4. Implement more specific selectors

Missing Repositories

Symptom: Expected repositories not appearing

Solutions:

1. Check namespace_pattern and repository_pattern match
2. Verify authentication has access
3. Review logs for errors
4. For GHCR: Ensure explicit repository names

Performance Tips

1. Limit tags: Use max_tags to reduce API calls
2. Specific patterns: Use precise regex patterns
3. Exclude unnecessary tags: Filter out dev/test tags
4. Adjust interval: Balance freshness vs. API usage
5. Disable vulnerabilities: Set discover_vulnerabilities: false unless needed

Integration Examples

Link Images to Deployments

Track which container images are deployed:

KubernetesDeployment --USES--> DockerImage

Link to CI/CD

Track which pipelines build images:

GithubAction --BUILDS--> DockerImage

Next Steps

• Configure GitHub molecule to link source repos
• Set up Argo CD molecule to track deployments
• Learn about entity relationships
• Explore vulnerability scanning integration