Setup guide

Reads quota, regions, flavors, catalog, existing networks, clusters, volumes and current usage before any design decision is made.

↳ Narrow to GET /cloud/project/<projectId>/* so one token cannot enumerate every project on the account.

Creates the private network, subnet, gateway, MKS cluster, node pools, Object Storage buckets, project users and S3 credentials.

↳ Narrow to POST /cloud/project/<projectId>/* and keep a separate read-only token for audit and cost-review runs.

Updates node pool sizing and autoscale bounds, cluster update policy, bucket versioning and lifecycle configuration.

↳ Scope to the project ID; PUT is not needed at all for a plan-only or audit-only run.

Required for terraform destroy and for sweeping detached volumes, unattached floating IPs and orphaned snapshots.

↳ Omit entirely from the CI token; grant DELETE only to a short-lived, human-triggered teardown credential.

IAM action wildcard granting the OAuth2 service account full control of Public Cloud resources on the projects targeted by the policy.

↳ Replace the wildcard with the specific actions the run needs, e.g. publicCloudProject:apiovh:quota/get, publicCloudProject:apiovh:kube/create, publicCloudProject:apiovh:network/private/create, publicCloudProject:apiovh:region/gateway/create.

The gate in step 2 of the procedure: reads instance, vCore, RAM and GPU quota per region before any HCL is written.

↳ This plus publicCloudProject:apiovh:region/get and publicCloudProject:apiovh:flavor/get is the whole read-only audit profile.

Creates the MKS cluster and its node pools, and retrieves the kubeconfig.

↳ Split cluster lifecycle onto its own service account so an app-deployment credential can never rebuild the control plane.

Public Cloud project user role. Needed once, on the human operator, to create other project users and their S3 credentials.

↳ Never attach this to the user whose openrc.sh the automation sources; use a task-scoped role instead.

Public Cloud project user role attached to the dedicated S3 user (ovh_cloud_project_user role_names) so the skill can create buckets, set versioning and apply lifecycle policies.

↳ This is already the narrow option - it grants Object Storage only and no compute, network or billing access.

Public Cloud project user role for the OpenStack CLI user: lists flavors and availability zones, manages instances, volumes and floating IPs.

↳ For a read-only inventory sweep, the authentication role alone is enough to obtain a Keystone token for list-only calls in some catalogs; verify before relying on it.

Public Cloud project user role required for the Octavia load balancer, listener, pool, health monitor and member operations and for Neutron port/subnet reads.

↳ Pair with network_security_operator only if the design also manages security groups; otherwise leave it off.

Cause: The OAuth2 service account has no IAM policy covering the called path, or the legacy consumer key was created without a rights line matching that method and path.

Fix: Add an IAM policy binding the service account to a resource group containing the project with the required publicCloudProject:apiovh:* actions, or re-issue the legacy token with GET/POST/PUT/DELETE on /cloud/project/*. Never widen a production token as a workaround - issue a new scoped one.

Cause: The OAuth2 token request at https://www.ovh.com/auth/oauth2/token was made with a mistyped OVH_CLIENT_ID/OVH_CLIENT_SECRET, a deleted service account, or against the wrong entity's token host.

Fix: Re-copy the client ID, recreate the service account if the secret was lost (it is shown once), and confirm the token host matches OVH_ENDPOINT - ovh-ca and ovh-us use their own auth hosts.

Cause: Legacy AK/AS/CK auth only. The application secret is wrong, or the local clock has drifted from the OVH API server time used in the request signature.

Fix: Re-check OVH_APPLICATION_SECRET, then sync the clock (chronyd/w32time). python-ovh calls /auth/time to compensate for drift; hand-rolled signers must do the same.

Cause: OVH_CLOUD_PROJECT_SERVICE points at a project that does not exist on the entity selected by OVH_ENDPOINT - almost always ovh-eu credentials pointed at an ovh-us/ovh-ca project or vice versa, or a truncated 32-hex ID.

Fix: Run GET /cloud/project with the same credentials and use an ID from that list. Confirm OVH_ENDPOINT before debugging anything else.

Cause: Keystone rejected the openrc credentials: the project user's password was regenerated, the user was deleted, or OS_PROJECT_ID/OS_TENANT_ID is missing from an older RC file.

Fix: Re-download openrc.sh from Users & Roles, regenerate the password if it was lost, and export both OS_PROJECT_ID and OS_TENANT_ID plus OS_IDENTITY_API_VERSION=3.

Cause: The node pool or instance request exceeds the region's default Public Cloud quota (roughly 20 instances / 20 vCores / 40 GB RAM per region, GPU quota separate and starting at 0).

Fix: Raise quota from Public Cloud > Quota and regions before applying, or reduce desired_nodes/max_nodes. Quota increases are processed manually, so request them ahead of the apply window.

Cause: The awscli --region value does not match the region embedded in the OVHcloud S3 endpoint host, so SigV4 signs with the wrong scope.

Fix: Keep them aligned: --endpoint-url https://s3.gra.io.cloud.ovh.net with --region gra. Also confirm the key pair belongs to this project - S3 keys are per project.

Cause: The S3 credential belongs to a project user that does not hold the objectstore_operator role, or the target region does not offer the requested storage class (HIGHPERFORMANCE is 1-AZ only, COLDARCHIVE is Paris only).

Fix: Attach objectstore_operator to the user (or create a dedicated one via ovh_cloud_project_user with role_names = ["objectstore_operator"]) and verify class availability for the region before setting --storage-class.

Cause: MKS nodes sit on a private network with no public IP and no managed gateway, so they cannot reach the registry. Cluster creation succeeded, node bootstrap did not.

Fix: Create an ovh_cloud_project_gateway (model s/m/l) on the subnet and add depends_on from the cluster to it. A gateway is mandatory for a multi-zone MKS cluster.

Cause: Raw 403 from the API host itself, typically ovh-eu credentials sent to https://api.us.ovhcloud.com or https://ca.api.ovh.com.

Fix: Echo OVH_ENDPOINT and the resolved base URL first; the three entities are separate companies and credentials are not portable between them.