Referenz zur Instanz-Konfiguration

Was diese Konfiguration steuert

In Craftifact ist Effektive Konfiguration die maßgebliche Instanz-Konfiguration. Darüber steuerst du Repositorys, Zugriffe, Storage-Referenzen, Robot-Accounts und Retention-Verhalten.

Der normale Workflow ist:

1. YAML in Effektive Konfiguration bearbeiten.
2. Secrets in Secrets anlegen oder aktualisieren, falls die Konfiguration ${VAR}-Platzhalter referenziert.
3. Speichern und validieren.
4. Mit Config deployen die gespeicherte Konfiguration zur aktiven Laufzeitkonfiguration machen.

Minimales Hosted-Beispiel

Das ist die praktische Basis, die der Hosted-Flow für eine neue Starter-Instanz anlegt:

storage:
  default: local-s3
  backends:
    local-s3:
      type: s3
      endpoint: ${S3_ENDPOINT}
      bucket: ${S3_BUCKET}
      credentials:
        access_key_id: ${S3_ACCESS_KEY}
        secret_access_key: ${S3_SECRET_KEY}

repositories:
  - name: oci
    type: oci

roles:
  - name: admin
    permissions:
      - "*:*:*"
  - name: developer
    permissions:
      - "oci:artifact:publish"
      - "oci:artifact:read"
      - "oci:artifact:redeploy"
      - "oci:artifact:delete"
      - "oci:composition:read"
      - "oci:findings:read"
  - name: viewer
    permissions:
      - "oci:artifact:read"
      - "oci:composition:read"
      - "oci:findings:read"
      - "oci:license_policy:read"
      - "oci:pull_gate:read"

role_assignments:
  - role: admin
    members:
      - admin@example.com

In der generierten Instanz-Konfiguration wird admin@example.com durch die initiale Admin-E-Mail ersetzt, die du beim Erstellen eingibst. Ab Pro enthält die angelegte Konfiguration zusätzlich Beispiel-retention_policies.

Was du als Nächstes typischerweise änderst

• Weitere Repositorys unter repositories ergänzen.
• Proxy-Zugangsdaten über Secrets hinterlegen und per ${VAR} in der Konfiguration referenzieren.
• roles, groups und role_assignments an deine Teamstruktur anpassen.
• retention_policies ergänzen, wenn du auf Pro oder höher bist.
• license_policies und pull_policies ergänzen, wenn du Supply-Chain-Gates auf Repository-Ebene brauchst.
• robot_accounts für Automatisierung ergänzen.
• Ab Team nur dann externen S3-kompatiblen Storage in Betracht ziehen, wenn du die Hosted-Defaults bewusst ersetzen willst.

Top-Level-Keys

storage

Pflichtfeld. Definiert das Standard-Storage-Backend und benannte Backends.

Unterstützte Backend-Typen sind:

• filesystem
• s3
• azure_blob
• google_cloud_storage

Hinweis für Craftifact-Instanzen:

• Unterhalb von Team akzeptiert die Validierung für S3 nur das interne Muster ${S3_ENDPOINT}, ${S3_BUCKET}, ${S3_ACCESS_KEY} und ${S3_SECRET_KEY}.
• Externer S3-kompatibler Storage ist ein Team-Feature.

repositories

Liste von Repository-Definitionen.

Unterstützte Repository-Typen in Craftifact sind:

• maven, python, npm, oci
• go beta
• maven_proxy, python_proxy, npm_proxy, oci_proxy
• go_proxy
• maven_group, python_group, npm_group, oci_group
• go_group

Häufig genutzte Felder sind:

• name
• type
• storage
• quota
• read_only
• redeploy
• upstream_url
• upstream_user
• upstream_password
• upstream_bearer_token
• upstream_tls_verify
• cache_ttl für Proxy-Repositorys
• members
• retention
• license_policy
• pull_policy
• version_policy für Maven

roles

Benannte Permission-Bündel. Permissions verwenden die Form <repository>:<domain>:<action>. Die Bedeutung der unterstützten Domain/Action-Paare steht in Berechtigungen und Zugriffsmodell.

artifact:* gewährt nur Artefakt-Actions. Nutze <repository>:*:* für alle Domains in einem Repository oder "*:*:*" für alle Repository-bezogenen Permissions.

Legacy-Permissions wie artifact:add, artifact:exec_elevated, artifact:manage_findings, artifact:manage_licenses, artifact:manage_policies und sbom:* werden nicht mehr akzeptiert. Verwende die domain-spezifischen Permissions oben.

Wenn du am Anfang eines Permission-Strings * nutzt, setze den kompletten Permission-String in YAML in Anführungszeichen, zum Beispiel "*:*:*". Ein führendes * ist sonst keine gültige unquoted YAML-Scalar-Syntax.

groups

Benannte Gruppendefinitionen für Rollen-Zuweisungen. Eine Gruppe muss genau eines davon definieren:

• mail_domain
• members
• idp_group

role_assignments

Bindet eine Rolle an eines oder beides:

• members
• groups

robot_accounts

Deklariert Automatisierungs-Identitäten. Wichtige Felder sind:

• id
• description
• owners
• roles
• enabled
• token_policy

Für den vollständigen Ablauf von der Deklaration bis zur Token-Nutzung im Tab Robot accounts siehe Robot-Account anlegen und Token nutzen.

retention_policies

Verfügbar ab Pro. Definiert benannte Retention-Policys und optional eine Default-Policy über retention_policies.default. Benannte Policys liegen unter retention_policies.<name>. Repositorys referenzieren sie später über repositories[].retention.

Praktisches Beispiel mit einer allgemeinen Default-Policy und einer selektorbasierten OCI-Policy:

retention_policies:
  default: default-policy

  default-policy:
    max_duration_since_published: 7d
    max_duration_since_download: 7d
    min_duration_since_published: 1d
    keep_last: 3

  oci-policy:
    selectors:
      name:
        include: "^(craftifact|saas-controller)$"
      version:
        include: "^[0-9]+\\.[0-9]+\\.[0-9]+$"
        exclude: "^latest$"
    keep_last: 3

Verfügbare Attribute pro Policy sind:

• max_duration_since_published Löscht Artefakte, die älter als diese Dauer seit Veröffentlichung sind.
• max_duration_since_download Löscht Artefakte, die länger als diese Dauer nicht heruntergeladen wurden.
• min_duration_since_published Erzwingt eine Mindestlebensdauer seit Veröffentlichung, bevor etwas gelöscht werden darf.
• keep_last Behält die letzten N passenden Artefakte unabhängig von den Zeitregeln.
• selectors Beschränkt eine Policy auf passende Artefakte nach Name und/oder Version.

Unter selectors sind verfügbar:

• selectors.name.include
• selectors.name.exclude
• selectors.version.include
• selectors.version.exclude

Alle vier erwarten Regex-Strings. Wenn selectors gesetzt ist, muss mindestens eines dieser vier Felder konfiguriert sein.

Kombinationsregeln:

• keep_last kann mit allen Zeitattributen kombiniert werden.
• selectors kann zusätzlich mit keep_last und den Zeitattributen kombiniert werden.
• Wenn selectors gesetzt ist, muss keep_last explizit gesetzt sein.
• Wenn selectors nicht gesetzt ist und keep_last fehlt, wird intern 0 verwendet.
• retention_policies.default muss auf eine definierte benannte Policy zeigen.
• Wenn retention_policies.default fehlt, werden Repositorys ohne eigene Retention-Konfiguration nicht automatisch durch eine Default-Policy abgedeckt.

Dauern verwenden die Suffixe h, d oder y, zum Beispiel 48h, 7d oder 1y.

license_policies

Definiert benannte Lizenz-Policys und optional eine Default-Policy über license_policies.default. Benannte Policys liegen unter license_policies.<name>. Repositorys können die Default-Policy verwenden, eine andere benannte Policy referenzieren, eine Inline-Policy definieren, Policy-Prüfung deaktivieren oder die Verwaltung an Nutzer mit license_policy:configure delegieren.

Lizenz-Policy-Hilfen in Craftifact sind rein informativ und keine Rechtsberatung. Hintergrund zu Kennungen und Lizenztexten findest du bei SPDX und ChooseALicense.

Beispiel für gemischte Governance:

license_policies:
  default: company-default

  company-default:
    denied_spdx_ids:
      - AGPL-3.0-only
      - AGPL-3.0-or-later
    unknown_license_action: unknown

  permissive-only:
    allowed_spdx_ids:
      - Apache-2.0
      - BSD-2-Clause
      - BSD-3-Clause
      - MIT
    unknown_license_action: unknown

repositories:
  - name: oci
    type: oci

  - name: research
    type: python
    license_policy:
      policy: permissive-only

  - name: delegated
    type: npm
    license_policy:
      managed_by_users: true

  - name: disabled
    type: maven
    license_policy: disabled

Regeln für Policys:

• allowed_spdx_ids erstellt eine Allowlist.
• denied_spdx_ids erstellt eine Denylist.
• Eine Policy muss genau eine dieser beiden Listen definieren.
• unknown_license_action akzeptiert allow, deny oder unknown; Default ist unknown.
• license_policy: disabled deaktiviert die Policy-Auswertung für dieses Repository, auch wenn eine Default-Policy existiert.
• managed_by_users: true ist exklusiv und darf nicht mit konkreten Policy-Einstellungen oder Referenzen auf benannte Policys kombiniert werden.

pull_policies

Definiert benannte Pull-Policys und optional eine Default-Policy über pull_policies.default. Benannte Policys liegen unter pull_policies.<name>. Repositorys können die Default-Policy verwenden, über pull_policy.policy eine andere benannte Policy referenzieren oder eine Inline-pull_policy definieren.

Pull-Policys gelten für npm-, Python-, Maven-, Go- und OCI-Pull-Pfade. Sie können Paketmetadaten filtern und direkte Pulls je nach Enforcement-Modus und Regelergebnis halten oder ablehnen. Group-Repositorys können keine eigene Pull-Policy definieren.

Cooldown-Fenster verzögern neu veröffentlichte Pakete, bis ein konfiguriertes Mindestalter erreicht ist. Fast-Track-Aktionen erstellen eine dokumentierte Ausnahme für ein gehaltenes Paket, damit vertrauenswürdige Releases die Wartezeit umgehen können, ohne die Policy für das Repository abzuschalten.

Praktisches Strict-Gate-Beispiel:

pull_policies:
  default: strict-release-gate

  strict-release-gate:
    enforcement_mode: strict
    cooldown:
      minimum_release_age: 24h
      unknown_release_time: hold
    vulnerabilities:
      max_severity: high
      unknown_analysis: hold
    licenses:
      source: repository_license_policy
      unknown_analysis: hold
    content:
      secrets: hold
      misconfig: allow
      malware: deny
    hosted:
      wait_for_required_scans: true

repositories:
  - name: npm
    type: npm_proxy

  - name: experimental
    type: python_proxy
    pull_policy:
      enforcement_mode: metadata_only
      cooldown:
        minimum_release_age: 12h

Regeln für Pull-Policys:

• enforcement_mode akzeptiert observe, metadata_only oder strict; Default ist observe.
• metadata_only blendet gehaltene Inhalte aus Paketmetadaten aus, direkte Pulls können aber weiterlaufen.
• strict kann direkte Pulls halten oder ablehnen und gibt für blockierte Requests Craftifact-Policy-Decision-Header zurück.
• cooldown.minimum_release_age akzeptiert Dauerwerte wie 12h oder 7d.
• cooldown.unknown_release_time akzeptiert allow, hold oder use_first_seen; Default ist allow.
• vulnerabilities.max_severity akzeptiert unknown, low, medium, high oder critical.
• vulnerabilities.unknown_analysis, licenses.unknown_analysis, content.secrets, content.misconfig und content.malware akzeptieren allow, hold oder deny; Default ist allow.
• licenses.source: repository_license_policy nutzt das Repository-Lizenzpolicy-Ergebnis als Pull-Gate-Eingang.
• hosted.wait_for_required_scans: true lässt Hosted-Artefakte in einem blockierenden Modus auf erforderliche Analysen warten.
• provenance.required: true ist reserviert und wird aktuell abgelehnt, weil Provenance-Enforcement noch nicht implementiert ist.

scheduler

Optionales Feintuning für Retention, Quota-Prüfungen, Stalled-Job-Retries und die Frequenz der OCI-Garbage-Collection. Die meisten Nutzer können das unverändert lassen.

Beispiel:

scheduler:
  retention:
    interval: 6h
    catchup: true
    max_lateness: 30m

  quota:
    interval: 6h
    catchup: true
    max_lateness: 30m

  vulnerability_rescan:
    interval: 1d

  stalled_job_retry:
    enabled: true
    max_attempts: 1

repositories:
  - name: team-images
    type: oci
    oci:
      gc:
        interval: "*/15 * * * *"
        max_lateness: 5m

Unterstützte Top-Level-Bereiche sind:

• retention
• quota
• vulnerability_rescan
• stalled_job_retry

scheduler.retention

Verfügbare Attribute sind:

• enabled
• interval
• catchup
• max_lateness

catchup und max_lateness wirken zusammen:

• Wenn ein Retention-Lauf später startet als max_lateness, wird er bei catchup: false übersprungen.
• Bei catchup: true läuft derselbe verspätete Job trotzdem noch.

scheduler.quota

Verfügbare Attribute sind:

• enabled
• interval
• catchup
• max_lateness

Semantisch funktioniert das wie bei scheduler.retention, nur für den Quota-Abgleich statt für Löschregeln.

scheduler.vulnerability_rescan

Verfügbare Attribute sind:

• interval

Craftifact startet den ersten Schwachstellen-Scan weiterhin, sobald eine hochgeladene oder generierte SBOM bereit ist. Diese Einstellung steuert nur die periodische Prüfung für bereits gespeicherte Berichte, die durch Schwachstellendatenbank, Scanner-Version, Scan-Status oder eine geänderte SBOM veraltet sind.

scheduler.stalled_job_retry

Verfügbare Attribute sind:

• enabled
• max_attempts

Das ist kein periodischer Sweep wie retention oder quota. Die Logik läuft beim Start eines Workers und versucht Jobs erneut anzustoßen, die vom Queue-System als hängen geblieben erkannt werden.

OCI Garbage Collection pro Repository

Für oci- und oci_proxy-Repositorys kannst du zusätzlich unter repositories[].oci.gc die Garbage Collection pro Repository feinjustieren.

Verfügbare Attribute sind:

• interval
• max_lateness

Wichtig:

• Es gibt kein scheduler.enabled. Scheduler-Registrierung ist immer aktiv.
• Es gibt auch kein repositories[].oci.gc.enabled. Für OCI-Repositorys ist die GC grundsätzlich aktiv; du steuerst nur Takt und max_lateness.
• Andere periodische Plattform-Jobs wie Procrastinate-Cleanup oder Checksum-Retries sind intern fest verdrahtet und nicht über diese YAML konfigurierbar.

Für Dauerwerte gelten hier die Suffixe s, m, h, d und w. Alternativ kannst du direkt eine Cron-Expression verwenden. Wenn du Dauerwerte statt Cron nutzt, sollten sie in der Praxis auf sinnvolle Minuten-, Stunden-, Tages- oder Wochenraster fallen.

Environment-Platzhalter und Secrets

Die Validierung erlaubt ${VAR}-Platzhalter nur an bestimmten Stellen:

• bei Credentials von Storage-Backends
• in repositories[].upstream_user
• in repositories[].upstream_password
• in repositories[].upstream_bearer_token

Für eigene Secrets legst du den Key im Tab Secrets an und referenzierst ihn in YAML als ${MY_SECRET}. Die Control Plane rendert ihn automatisch in die Runtime-Umgebung mit Präfix. Lege Zugangsdaten, Passwörter oder Tokens dort nicht im Klartext ab, sondern immer über Secrets und ${...}-Referenzen.

Geh nicht davon aus, dass irgendwelche anderen Plattform-Environment-Variablen aufgelöst werden, nur weil sie irgendwo in der Infrastruktur existieren.

Wohin danach

• Für Repository-Lifecycle-Verhalten nach Config-Änderungen siehe Repository-Lebenszyklus.
• Für den nächsten Schritt nach erzeugten Restore-Snippets siehe Import aus Nexus.
• Für format-spezifische Stolperstellen siehe Hinweise zu Paketformaten.