Spegel Documentation

repository·main·Indexed 25 days ago

https://github.com/spegel-org/spegel

Spegel is a stateless, cluster-local OCI registry mirror designed to cache images from external registries to improve pull speeds, reduce egress traffic, and provide resilience against external registry downtime. It includes a CLI for managing containerd mirror configurations, a registry server with P2P routing, and a Go client for interacting with OCI registries.

Tokens
6.6K
Snippets
4
Records
17
Agent score
84%

What's inside Spegel

  1. Overview of Spegel

    main

    Spegel is a stateless, cluster-local OCI registry mirror. It is designed to locally cache images from external registries without requiring explicit configuration.

    Key benefits include:

    • Improved Performance: Faster image pulls and pod startup times by prioritizing the local cache.
    • Resilience: Avoids cluster failure during external registry downtime.
    • Cost & Efficiency: Decreases egress traffic outside the cluster network and increases pull efficiency in edge node deployments.
    • Rate-Limit Avoidance: Helps prevent rate-limiting from external registries like Docker Hub.
  2. Configure Spegel Helm Chart values

    main

    The Spegel Helm chart provides numerous configuration options for deployment, including image settings, resource management, security contexts, and registry mirroring behavior.

    Key configuration groups include:

    • Image Configuration: Control the repository, tag, digest, and pull policy using image.repository, image.tag, image.digest, and image.pullPolicy.
    • Registry Mirroring: Configure which registries are mirrored via spegel.mirroredRegistries and add extra targets with spegel.additionalMirrorTargets. Use spegel.registryFilters (regex) to filter tags/registries.
    • Containerd Integration: Spegel interacts with containerd via spegel.containerdSocket, spegel.containerdNamespace, and spegel.containerdRegistryConfigPath.
    • Persistence: Enable host-path persistence using spegel.persistence.enabled and specify paths with spegel.persistence.hostPath and spegel.persistence.path.
    • Observability: Enable Grafana dashboards via grafanaDashboard.enabled and Prometheus Service Monitors via serviceMonitor.enabled.
    • Security: Configure podSecurityContext, securityContext (for the container), and networkPolicy.enabled to limit libp2p router traffic.
  3. Reference: Spegel Helm Chart Values

    main

    The following table lists the available configuration keys for the Spegel Helm chart.

    | Key | Type | Default | Description |
    |-----|------|---------|-------------|
    | affinity | object | `{}` | Affinity settings for pod assignment. |
    | basicAuthSecretName | string | `""` | Name of secret containing basic authentication credentials for registry. |
    | clusterDomain | string | `"cluster.local."` | Domain configured for service domain names. |
    | commonLabels | object | `{}` | Common labels to apply to all rendered resources. |
    | daemonsetAnnotations | object | `{}` | Annotations to add to the DaemonSet. |
    | extraInitContainers | list | `[]` | Add additional initContainers *before* Spegel's own configuration init container to run additional node init configuration tasks |
    | extraVolumes | list | `[]` | Add additional volumes to the daemonset. This can be helpful when adding custom init containers that need host path mounts to different locations than the already configured ones. |
    | fullnameOverride | string | `""` | Overrides the full name of the chart. |
    | grafanaDashboard.annotations | object | `{}` | Annotations to add to the Sidecar configMap or GrafanaDashboard. |
    | grafanaDashboard.enabled | bool | `false` | If true creates a Grafana dashboard. |
    | grafanaDashboard.grafanaOperator.allowCrossNamespaceImport | bool | `true` | If true allows for a Grafana in any namespace to access this GrafanaDashboard. |
    | grafanaDashboard.grafanaOperator.folder | string | `""` | Folder to create the dashboard in. |
    | grafanaDashboard.grafanaOperator.matchLabels | object | `{}` | Selected labels for Grafana instance. |
    | grafanaDashboard.grafanaOperator.resyncPeriod | string | `"10m"` | Resync period for the Grafana operator to check for updates to the dashboard. |
    | grafanaDashboard.labels | object | `{}` | Labels to add to the Sidecar configMap or GrafanaDashboard. |
    | grafanaDashboard.mode | string | `"Sidecar"` | Mode for Grafana dashboard creation. Valid values are `Sidecar` and `GrafanaOperator`. |
    | image.digest | string | `""` | Image digest. |
    | image.pullPolicy | string | `"IfNotPresent"` | Image Pull Policy. |
    | image.repository | string | `"ghcr.io/spegel-org/spegel"` | Image repository. |
    | image.tag | string | `""` | Overrides the image tag whose default is the chart appVersion. |
    | imagePullSecrets | list | `[]` | Image Pull Secrets |
    | livenessProbe.enabled | bool | `false` | When enabled a liveness probe will be added to the registry. |
    | nameOverride | string | `""` | Overrides the name of the chart. |
    | namespaceOverride | string | `""` | Overrides the namespace where spegel resources are installed. |
    | networkPolicy.enabled | bool | `false` | If true creates a NetworkPolicy that limits libp2p router traffic to Spegel peers in the release namespace. |
    | nodeSelector | object | `{"kubernetes.io/os":"linux"}` | Node selector for pod assignment. |
    | podAnnotations | object | `{}` | Annotations to add to the pod. |
    | podSecurityContext | object | `{}` | Security context for the pod. |
    | priorityClassName | string | `"system-node-critical"` | Priority class name to use for the pod. |
    | resources | object | `{"limits":{"memory":"128Mi"},"requests":{"memory":"128Mi"}}` | Resource requests and limits for the Spegel container. |
    | revisionHistoryLimit | int | `10` | The number of old history to retain to allow rollback. |
    | securityContext | object | `{"readOnlyRootFilesystem":true}` | Security context for the Spegel container. |
    | service.bootstrap.annotations | object | `{}` | Annotations to add to the bootstrap service |
    | service.cleanup.annotations | object | `{}` | Annotations to add to the cleanup service (used in post-delete hook) |
    | service.cleanup.port | int | `8080` | Port to expose cleanup probe on. |
    | service.metrics.annotations | object | `{}` | Annotations to add to the metrics service |
    | service.metrics.port | int | `9090` | Port to expose the metrics via the service. |
    | service.registry.annotations | object | `{}` | Annotations to add to the registry service |
    | service.registry.internalTrafficLocal | bool | `false` | Enable internalTrafficPolicy: Local. This is only for 1.33 clusters compatibility instead of PreferSameNode. |
    | service.registry.nodeIp | string | `""` | Override the NODE_ID environment variable. It defaults to the field status.hostIP |
    | service.registry.nodePort | int | `30020` | Node port to expose the registry via the service. |
    | service.registry.port | int | `5000` | Port to expose the registry via the service. |
    | service.router.port | int | `5001` | Port to expose the router via the service. |
    | serviceAccount.annotations | object | `{}` | Annotations to add to the service account |
    | serviceAccount.name | string | `""` | The name of the service account to use. If not set and create is true, a name is generated using the fullname template. |
    | serviceMonitor.enabled | bool | `false` | If true creates a Prometheus Service Monitor. |
    | serviceMonitor.interval | string | `"60s"` | Prometheus scrape interval. |
    | serviceMonitor.labels | object | `{}` | Service monitor specific labels for prometheus to discover servicemonitor. |
    | serviceMonitor.metricRelabelings | list | `[]` | List of relabeling rules to apply to the samples before ingestion. |
    | serviceMonitor.relabelings | list | `[]` | List of relabeling rules to apply the target’s metadata labels. |
    | serviceMonitor.scrapeTimeout | string | `"30s"` | Prometheus scrape interval timeout. |
    | spegel.additionalMirrorTargets | list | `[]` | Additional target mirror registries other than Spegel. |
    | spegel.containerdContentPath | string | `"/var/lib/containerd/io.containerd.content.v1.content"` | Path to Containerd content store.. |
    | spegel.containerdMirrorAdd | bool | `true` | If true Spegel will add mirror configuration to the node. |
    | spegel.containerdNamespace | string | `"k8s.io"` | Containerd namespace where images are stored. |
    | spegel.containerdRegistryConfigPath | string | `"/etc/containerd/certs.d"` | Path to Containerd mirror configuration. |
    | spegel.containerdSock | string | `"/run/containerd/containerd.sock"` | Path to Containerd socket. |
    | spegel.debugWebEnabled | bool | `true` | When true enables debug web page. |
    | spegel.logLevel | string | `"INFO"` | Minimum log level to output. Value should be DEBUG, INFO, WARN, or ERROR. |
    | spegel.mirrorResolveRetries | int | `3` | Max amount of mirrors to attempt. |
    | spegel.mirrorResolveTimeout | string | `"20ms"` | Max duration spent finding a mirror. |
    | spegel.mirroredRegistries | list | `[]` | Registries for which mirror configuration will be created. Empty means all registires will be mirrored. |
    | spegel.persistence.enabled | bool | `true` | If true Spegel will persist data on the host. |
    | spegel.persistence.hostPath | string | `"/var/lib/spegel"` | Path on host which is mounted to container. |
    | spegel.persistence.path | string | `"/var/lib/spegel"` | Path in the container where host path is mounted. |
    | spegel.prependExisting | bool | `false` | When true existing mirror configuration will be kept and Spegel will prepend it's configuration. |
    | spegel.registryFilters | list | `[]` | Regular expressions to filter out tags/registries. If empty, all registries/tags are resolved. |
    | spegel.resolveTags | bool | `true` | When true Spegel will resolve tags to digests. |
    | tolerations | list | `[{"key":"CriticalAddonsOnly","operator":"Exists"},{"effect":"NoExecute","operator":"Exists"},{"effect":"NoSchedule","operator":"Exists"}]` | Tolerations for pod assignment. |
    | updateStrategy | object | `{}` | An update strategy to replace existing pods with new pods. |
    | verticalPodAutoscaler.controlledResources | list | `[]` | List of resources that the vertical pod autoscaler can control. Defaults to cpu and memory |
    | verticalPodAutoscaler.controlledValues | string | `"RequestsAndLimits"` | Specifies which resource values should be controlled: RequestsOnly or RequestsAndLimits. |
    | verticalPodAutoscaler.enabled | bool | `false` | If true creates a Vertical Pod Autoscaler. |
    | verticalPodAutoscaler.maxAllowed | object | `{}` | Define the max allowed resources for the pod |
    | verticalPodAutoscaler.minAllowed | object | `{}` | Define the min allowed resources for the pod |
    | verticalPodAutoscaler.recommenders | list | `[]` | Recommender responsible for generating recommendation for the object. List should be empty (then the default recommender will generate the recommendation) or contain exactly one recommender. |
    | verticalPodAutoscaler.updatePolicy.minReplicas | int | `2` | Specifies minimal number of replicas which need to be alive for VPA Updater to attempt pod eviction |
    | verticalPodAutoscaler.updatePolicy.updateMode | string | `"Auto"` | Specifies whether recommended updates are applied when a Pod is started and whether recommended updates are applied during the life of a Pod. Possible values are "Off", "Initial", "Recreate", and "Auto". |
  4. Initialize an OCI Client with NewClient

    main

    Use NewClient to create a new Client instance for interacting with OCI registries. You can provide optional configuration using WithTLS to specify custom root CAs and client certificates.

    Returns a *Client and an error if configuration fails.

  5. Fetch OCI resources using the Client.Fetch method

    main

    The Fetch method performs a low-level HTTP request to retrieve an OCI resource (manifest or blob) defined by a DistributionPath. It returns an io.ReadCloser for the body and an ocispec.Descriptor describing the content.

    Supported FetchOptions:

    • WithFetchMirror(mirror *url.URL): Redirect fetch requests to a mirror.
    • WithFetchHeader(k, v string): Set a specific header key/value pair.
    • WithFetchUserinfo(userinfo *url.Userinfo): Provide credentials for authentication.

    Note: The caller is responsible for closing the returned io.ReadCloser to avoid leaking connections.

  6. Pull images using the Client.Pull method

    main

    The Pull method retrieves an image and its associated layers/manifests. It returns a slice of PullMetric objects containing metadata about each component pulled (digest, content type, size, and duration).

    Supported PullOptions:

    • WithPullMirror(mirror *url.URL): Redirect pulls to a specific mirror URL.
    • WithPullHeader(header http.Header): Add custom HTTP headers to the request.
    • WithPullUserinfo(userinfo *url.Userinfo): Provide credentials for authentication.
    • WithPullPlatform(platform ocispec.Platform): Specify the target architecture/platform (e.g., linux/amd64).
  7. Reference: OCI Client Pull Options

    main

    Options available for the Pull method to configure the image retrieval process.

    WithPullMirror(mirror *url.URL)
    WithPullHeader(header http.Header)
    WithPullUserinfo(userinfo *url.Userinfo)
    WithPullPlatform(platform ocispec.Platform)