diff --git a/AGENTS.md b/AGENTS.md index 72b8003..fd851e9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,6 +22,14 @@ The rendered profile content lives in `profile/README.md`. - After README changes, scan for broken relative asset links. - Preview rendered Markdown before shipping visual changes. +## GitHub Actions runners + +- Read [RUNNERS.md](RUNNERS.md) before selecting a self-hosted runner label. +- Treat [runner-profiles.json](runner-profiles.json) as the machine-readable + resource and capability contract. +- Use only the stable labels in that catalog; do not encode backend, runtime, + provider, or node details in repository workflows. + ## Maintaining this file Keep this file for knowledge useful to almost every future agent session in this diff --git a/README.md b/README.md index fba4147..21265fb 100644 --- a/README.md +++ b/README.md @@ -5,13 +5,8 @@ This repository maintains the public GitHub organization profile for `akua-dev`. The rendered organization profile lives in [profile/README.md](profile/README.md). -This change installs the base-owned, secret-free validation infrastructure for -the provider-neutral runner catalog. It intentionally publishes no runner -catalog yet. - -After this bootstrap merges to `main`, create the follow-up catalog publication -change from that merge commit. That change adds `RUNNERS.md`, -`runner-profiles.yaml`, `runner-profiles.json`, and -`runner-catalog-manifest.json`; its pull request is then checked by the -base-owned [`runner-catalog-trusted.yml`](.github/workflows/runner-catalog-trusted.yml) -workflow against the private `akua-dev/gitops` source. +The organization-wide, provider-neutral GitHub Actions contract is documented +in [RUNNERS.md](RUNNERS.md). Machine consumers can use +[runner-profiles.yaml](runner-profiles.yaml) or +[runner-profiles.json](runner-profiles.json); provenance is bound to the private +GitOps source by [runner-catalog-manifest.json](runner-catalog-manifest.json). diff --git a/RUNNERS.md b/RUNNERS.md new file mode 100644 index 0000000..29bab65 --- /dev/null +++ b/RUNNERS.md @@ -0,0 +1,83 @@ +# Akua GitHub Actions runner profiles + +This provider-neutral catalog defines the stable runner labels and their conservative guarantees. +Workflows select a label by declared resources and capabilities; the implementation behind a label may change without repository edits. +Capacity is shared across all profiles and capped at 4 concurrent jobs. A label does not reserve a private slot. + + + +## Selection rules + +1. Select the first profile whose guaranteed resources meet the declared requirements and whose capabilities contain every required capability. +2. Use the stable label in workflow configuration; do not infer implementation details from the label. +3. Use `akua-heavy-ci-v2` only when requirements exceed Docker but fit Heavy: 4 vCPU, 7168 MiB memory and 20480 MiB usable disk. +Requirements above Heavy, or capabilities absent from every profile, require an external runner or reduced requirements. +Required-resource inputs are supplied through AKUA_CI_REQUIRED_VCPU, AKUA_CI_REQUIRED_MEMORY_MIB and AKUA_CI_REQUIRED_DISK_MIB. + +## Profile guarantees + +| Label | Profile | Minimum CPU | Minimum memory | Minimum usable disk | Guaranteed capabilities | Status | Deprecation | +| --- | --- | ---: | ---: | ---: | --- | --- | --- | +| `akua-x64-ci-v2` | Standard | 2 vCPU | 4096 MiB | 10240 MiB | ordinary build and test tooling | active | not deprecated | +| `akua-docker-ci-v2` | Docker | 4 vCPU | 6144 MiB | 15360 MiB | Docker, Buildx, service containers, privileged containers, ordinary build and test tooling | active | not deprecated | +| `akua-heavy-ci-v2` | Heavy | 4 vCPU | 7168 MiB | 20480 MiB | Docker, Buildx, service containers, privileged containers, ordinary build and test tooling | active | not deprecated | + +## `akua-x64-ci-v2` + +Recommended uses: +- linting, formatting, unit tests and ordinary compilation +- jobs that do not start containers or require large local caches + +Exclusions: +- Docker, Buildx and service containers +- workloads whose requirements exceed the Standard guarantees + +## `akua-docker-ci-v2` + +Recommended uses: +- Docker and Buildx image builds +- integration tests using Docker or service containers + +Exclusions: +- workloads whose requirements exceed the Docker guarantees; use Heavy only when all Heavy bounds fit + +## `akua-heavy-ci-v2` + +Recommended uses: +- memory-heavy compilation, packaging and browser or integration suites that fit the Heavy guarantees +- Docker jobs whose declared requirements exceed Docker but fit Heavy + +Exclusions: +- workloads requiring more than 4 vCPU, 7168 MiB memory or 20480 MiB usable disk; use an external runner or reduce requirements + +## Versioning and deprecation + +The public contract version is 2.0.0. Profiles are active and not deprecated unless the structured catalog says otherwise. +The machine-readable catalogs and provenance manifest are the canonical serialized projections of this document. + diff --git a/profile/README.md b/profile/README.md index d7c395e..d1d0bd9 100644 --- a/profile/README.md +++ b/profile/README.md @@ -29,6 +29,8 @@ software from one workspace. - [Docs](https://docs.akua.dev) - learn the platform concepts and workflows. - [AI & Agents](https://docs.akua.dev/ai) - connect external AI tools through MCP or use hosted agents in the dashboard. +- [GitHub Actions runner profiles](../RUNNERS.md) - select the stable + self-hosted CI label by declared resources and capabilities. - [Bring your own cloud](https://docs.akua.dev/platform/byoc) - understand how Akua works with infrastructure you own. diff --git a/runner-catalog-manifest.json b/runner-catalog-manifest.json new file mode 100644 index 0000000..908d137 --- /dev/null +++ b/runner-catalog-manifest.json @@ -0,0 +1,161 @@ +{ + "manifestVersion": 1, + "source": { + "repository": "akua-dev/gitops", + "path": "clusters/agentos/runner-platform/profiles.yaml", + "revision": "59234e828aa544b2079404ffccd12d334567c0ac", + "sha256": "00a7ffd62374be2919214455967c06befc4f29c9425b682e07290e5606bca7e5" + }, + "catalog": { + "apiVersion": "runners.akua.dev/v1alpha1", + "kind": "RunnerProfileCatalog", + "metadata": { + "name": "akua-ci-catalog", + "contractVersion": "2.0.0", + "documentation": "https://github.com/akua-dev/.github/blob/main/RUNNERS.md", + "provenance": { + "repository": "akua-dev/gitops", + "path": "clusters/agentos/runner-platform/profiles.yaml", + "revision": "59234e828aa544b2079404ffccd12d334567c0ac", + "sha256": "00a7ffd62374be2919214455967c06befc4f29c9425b682e07290e5606bca7e5" + } + }, + "capacity": { + "scope": "organization", + "allocation": "shared", + "maxConcurrentJobs": 4, + "queueSlo": null, + "notes": [ + "Capacity is shared by all three profiles; a profile label does not reserve a private slot.", + "Four concurrent jobs are the current safe contract. Six was only a short load experiment." + ] + }, + "policy": { + "requirementEnvironment": { + "cpu": "AKUA_CI_REQUIRED_VCPU", + "memoryMiB": "AKUA_CI_REQUIRED_MEMORY_MIB", + "diskMiB": "AKUA_CI_REQUIRED_DISK_MIB" + }, + "selection": { + "safeMatch": { + "resources": "required-at-most-guaranteed-minimum", + "capabilities": "required-subset-of-guaranteed" + }, + "order": [ + "akua-x64-ci-v2", + "akua-docker-ci-v2", + "akua-heavy-ci-v2" + ], + "noMatch": "external-runner-or-reduce-requirements" + } + }, + "profiles": [ + { + "id": "standard-v2", + "label": "akua-x64-ci-v2", + "class": "standard", + "displayName": "Standard", + "status": "active", + "minimumResources": { + "vcpu": 2, + "memoryMiB": 4096, + "usableDiskMiB": 10240 + }, + "capabilities": { + "guaranteed": [ + "ordinary build and test tooling" + ] + }, + "workload": { + "recommended": [ + "linting, formatting, unit tests and ordinary compilation", + "jobs that do not start containers or require large local caches" + ], + "exclusions": [ + "Docker, Buildx and service containers", + "workloads whose requirements exceed the Standard guarantees" + ] + }, + "deprecation": { + "deprecated": false, + "announcedAt": null, + "sunsetAt": null, + "replacementLabel": null + } + }, + { + "id": "docker-v2", + "label": "akua-docker-ci-v2", + "class": "docker", + "displayName": "Docker", + "status": "active", + "minimumResources": { + "vcpu": 4, + "memoryMiB": 6144, + "usableDiskMiB": 15360 + }, + "capabilities": { + "guaranteed": [ + "Docker", + "Buildx", + "service containers", + "privileged containers", + "ordinary build and test tooling" + ] + }, + "workload": { + "recommended": [ + "Docker and Buildx image builds", + "integration tests using Docker or service containers" + ], + "exclusions": [ + "workloads whose requirements exceed the Docker guarantees; use Heavy only when all Heavy bounds fit" + ] + }, + "deprecation": { + "deprecated": false, + "announcedAt": null, + "sunsetAt": null, + "replacementLabel": null + } + }, + { + "id": "heavy-v2", + "label": "akua-heavy-ci-v2", + "class": "heavy", + "displayName": "Heavy", + "status": "active", + "minimumResources": { + "vcpu": 4, + "memoryMiB": 7168, + "usableDiskMiB": 20480 + }, + "capabilities": { + "guaranteed": [ + "Docker", + "Buildx", + "service containers", + "privileged containers", + "ordinary build and test tooling" + ] + }, + "workload": { + "recommended": [ + "memory-heavy compilation, packaging and browser or integration suites that fit the Heavy guarantees", + "Docker jobs whose declared requirements exceed Docker but fit Heavy" + ], + "exclusions": [ + "workloads requiring more than 4 vCPU, 7168 MiB memory or 20480 MiB usable disk; use an external runner or reduce requirements" + ] + }, + "deprecation": { + "deprecated": false, + "announcedAt": null, + "sunsetAt": null, + "replacementLabel": null + } + } + ] + } +} + diff --git a/runner-profiles.json b/runner-profiles.json new file mode 100644 index 0000000..08b90a9 --- /dev/null +++ b/runner-profiles.json @@ -0,0 +1,152 @@ +{ + "apiVersion": "runners.akua.dev/v1alpha1", + "kind": "RunnerProfileCatalog", + "metadata": { + "name": "akua-ci-catalog", + "contractVersion": "2.0.0", + "documentation": "https://github.com/akua-dev/.github/blob/main/RUNNERS.md", + "provenance": { + "repository": "akua-dev/gitops", + "path": "clusters/agentos/runner-platform/profiles.yaml", + "revision": "59234e828aa544b2079404ffccd12d334567c0ac", + "sha256": "00a7ffd62374be2919214455967c06befc4f29c9425b682e07290e5606bca7e5" + } + }, + "capacity": { + "scope": "organization", + "allocation": "shared", + "maxConcurrentJobs": 4, + "queueSlo": null, + "notes": [ + "Capacity is shared by all three profiles; a profile label does not reserve a private slot.", + "Four concurrent jobs are the current safe contract. Six was only a short load experiment." + ] + }, + "policy": { + "requirementEnvironment": { + "cpu": "AKUA_CI_REQUIRED_VCPU", + "memoryMiB": "AKUA_CI_REQUIRED_MEMORY_MIB", + "diskMiB": "AKUA_CI_REQUIRED_DISK_MIB" + }, + "selection": { + "safeMatch": { + "resources": "required-at-most-guaranteed-minimum", + "capabilities": "required-subset-of-guaranteed" + }, + "order": [ + "akua-x64-ci-v2", + "akua-docker-ci-v2", + "akua-heavy-ci-v2" + ], + "noMatch": "external-runner-or-reduce-requirements" + } + }, + "profiles": [ + { + "id": "standard-v2", + "label": "akua-x64-ci-v2", + "class": "standard", + "displayName": "Standard", + "status": "active", + "minimumResources": { + "vcpu": 2, + "memoryMiB": 4096, + "usableDiskMiB": 10240 + }, + "capabilities": { + "guaranteed": [ + "ordinary build and test tooling" + ] + }, + "workload": { + "recommended": [ + "linting, formatting, unit tests and ordinary compilation", + "jobs that do not start containers or require large local caches" + ], + "exclusions": [ + "Docker, Buildx and service containers", + "workloads whose requirements exceed the Standard guarantees" + ] + }, + "deprecation": { + "deprecated": false, + "announcedAt": null, + "sunsetAt": null, + "replacementLabel": null + } + }, + { + "id": "docker-v2", + "label": "akua-docker-ci-v2", + "class": "docker", + "displayName": "Docker", + "status": "active", + "minimumResources": { + "vcpu": 4, + "memoryMiB": 6144, + "usableDiskMiB": 15360 + }, + "capabilities": { + "guaranteed": [ + "Docker", + "Buildx", + "service containers", + "privileged containers", + "ordinary build and test tooling" + ] + }, + "workload": { + "recommended": [ + "Docker and Buildx image builds", + "integration tests using Docker or service containers" + ], + "exclusions": [ + "workloads whose requirements exceed the Docker guarantees; use Heavy only when all Heavy bounds fit" + ] + }, + "deprecation": { + "deprecated": false, + "announcedAt": null, + "sunsetAt": null, + "replacementLabel": null + } + }, + { + "id": "heavy-v2", + "label": "akua-heavy-ci-v2", + "class": "heavy", + "displayName": "Heavy", + "status": "active", + "minimumResources": { + "vcpu": 4, + "memoryMiB": 7168, + "usableDiskMiB": 20480 + }, + "capabilities": { + "guaranteed": [ + "Docker", + "Buildx", + "service containers", + "privileged containers", + "ordinary build and test tooling" + ] + }, + "workload": { + "recommended": [ + "memory-heavy compilation, packaging and browser or integration suites that fit the Heavy guarantees", + "Docker jobs whose declared requirements exceed Docker but fit Heavy" + ], + "exclusions": [ + "workloads requiring more than 4 vCPU, 7168 MiB memory or 20480 MiB usable disk; use an external runner or reduce requirements" + ] + }, + "deprecation": { + "deprecated": false, + "announcedAt": null, + "sunsetAt": null, + "replacementLabel": null + } + } + ] +} + diff --git a/runner-profiles.yaml b/runner-profiles.yaml new file mode 100644 index 0000000..686659a --- /dev/null +++ b/runner-profiles.yaml @@ -0,0 +1,119 @@ +--- +apiVersion: runners.akua.dev/v1alpha1 +kind: RunnerProfileCatalog +metadata: + name: akua-ci-catalog + contractVersion: 2.0.0 + documentation: https://github.com/akua-dev/.github/blob/main/RUNNERS.md + provenance: + repository: akua-dev/gitops + path: clusters/agentos/runner-platform/profiles.yaml + revision: 59234e828aa544b2079404ffccd12d334567c0ac + sha256: 00a7ffd62374be2919214455967c06befc4f29c9425b682e07290e5606bca7e5 +capacity: + scope: organization + allocation: shared + maxConcurrentJobs: 4 + queueSlo: + notes: + - Capacity is shared by all three profiles; a profile label does not reserve a private + slot. + - Four concurrent jobs are the current safe contract. Six was only a short load + experiment. +policy: + requirementEnvironment: + cpu: AKUA_CI_REQUIRED_VCPU + memoryMiB: AKUA_CI_REQUIRED_MEMORY_MIB + diskMiB: AKUA_CI_REQUIRED_DISK_MIB + selection: + safeMatch: + resources: required-at-most-guaranteed-minimum + capabilities: required-subset-of-guaranteed + order: + - akua-x64-ci-v2 + - akua-docker-ci-v2 + - akua-heavy-ci-v2 + noMatch: external-runner-or-reduce-requirements +profiles: +- id: standard-v2 + label: akua-x64-ci-v2 + class: standard + displayName: Standard + status: active + minimumResources: + vcpu: 2 + memoryMiB: 4096 + usableDiskMiB: 10240 + capabilities: + guaranteed: + - ordinary build and test tooling + workload: + recommended: + - linting, formatting, unit tests and ordinary compilation + - jobs that do not start containers or require large local caches + exclusions: + - Docker, Buildx and service containers + - workloads whose requirements exceed the Standard guarantees + deprecation: + deprecated: false + announcedAt: + sunsetAt: + replacementLabel: +- id: docker-v2 + label: akua-docker-ci-v2 + class: docker + displayName: Docker + status: active + minimumResources: + vcpu: 4 + memoryMiB: 6144 + usableDiskMiB: 15360 + capabilities: + guaranteed: + - Docker + - Buildx + - service containers + - privileged containers + - ordinary build and test tooling + workload: + recommended: + - Docker and Buildx image builds + - integration tests using Docker or service containers + exclusions: + - workloads whose requirements exceed the Docker guarantees; use Heavy only when + all Heavy bounds fit + deprecation: + deprecated: false + announcedAt: + sunsetAt: + replacementLabel: +- id: heavy-v2 + label: akua-heavy-ci-v2 + class: heavy + displayName: Heavy + status: active + minimumResources: + vcpu: 4 + memoryMiB: 7168 + usableDiskMiB: 20480 + capabilities: + guaranteed: + - Docker + - Buildx + - service containers + - privileged containers + - ordinary build and test tooling + workload: + recommended: + - memory-heavy compilation, packaging and browser or integration suites that fit + the Heavy guarantees + - Docker jobs whose declared requirements exceed Docker but fit Heavy + exclusions: + - workloads requiring more than 4 vCPU, 7168 MiB memory or 20480 MiB usable disk; + use an external runner or reduce requirements + deprecation: + deprecated: false + announcedAt: + sunsetAt: + replacementLabel: +