Configuration

This page is the exact lookup for where and how a Job, Service, or VM runs. For decision guidance, start with GPUs & VM Types, Cloud Credentials, and Buckets.

Configuration mappings

Purpose	CLI	Generated request field	Notes
Worker target	job --worker ID-OR-NAME	worker	Identity-only Job; no per-Job overrides
Kubernetes cluster	worker create --cluster ID-OR-NAME	CreateWorkerInput.cluster	Placement for the Worker
Worker GPU count	worker create --gpus COUNT	CreateWorkerInput.gpu_count	Quantity only; Cluster VM type supplies model
Compute credential	--credentials NAME	credentialName	Required for remote compute
Region	--region REGION	cloudConfig.region	Omit for normal multi-region selection
GPU model and count	--gpu-type TYPE	gpuType	Mutually exclusive with exact VM
Exact VM	--vm-type TYPE	cloudConfig.vmType	Mutually exclusive with GPU type
Spot	--spot	cloudConfig.spot	Jobs only
Root disk capacity	--disk-size GB	cloudConfig.diskSizeGb	Independent of performance tier
Root disk tier	--disk-tier TIER	cloudConfig.diskTier	medium, high, or ultra
Availability zone	--zone ZONE	cloudConfig.availabilityZone	Provider-specific value
Input Bucket	--input-bucket NAME	cloudConfig.inputBucket	Jobs only; must exist
Output Bucket	--output-bucket NAME	cloudConfig.outputBucket	Jobs only; created if needed
Checkpoint Bucket	--checkpoint-bucket NAME	cloudConfig.checkpointBucket	Jobs and VM-backed Services; must exist
Environment	-e, --env-file	env	Explicit values override Secret keys
Named Secret	--secret NAME	secrets	Repeatable
Container runtime	Docker flags below	dockerOptions	Applies after hardware resolution

Credential precedence

The generated client sends either credentialName or inline cloudConfig.credentials exactly as supplied in DeploymentAdmissionInput:

from anycloud.models.deployment_admission_input import DeploymentAdmissionInput

saved = DeploymentAdmissionInput.from_dict(
    {
        "image": "IMAGE",
        "credentialName": "production-aws",
        "cloudConfig": {"region": "us-east-1"},
    }
)

A CLI --credentials value wins over the ANYCLOUD_CREDENTIALS_NAME environment fallback. If both are absent, the CLI automatically selects the sole saved credential. With several saved credentials, an interactive terminal shows a picker; non-interactive use must pass --credentials. Inline credential environment variables are also accepted. Local deployments do not require a cloud credential. Workers use their Cluster's capacity identity rather than a per-Job compute credential.

Remote API requests must contain one resolved named or inline compute credential. If that credential fails authentication, the deployment becomes invalid; Anycloud does not switch accounts. Leave region unset to retain regional failover within the selected account.

Hardware constraints

gpu / --gpu-type and vm_type / --vm-type are mutually exclusive.

• GPU selection accepts a model with optional count, such as h100 or a100:8.
• VM selection accepts a provider-specific instance type, such as g6e.xlarge, Standard_NC40ads_H100_v5, or n1-standard-8.
• Repeating a CLI GPU or VM flag creates an ordered fallback pool. The generated admission model accepts the corresponding contract union.
• --gpus is a Docker exposure setting; it does not select the cloud VM.

# Ordered GPU preference
anycloud job IMAGE \
  --gpu-type h100:8 \
  --gpu-type a100:8

# Exact VM
anycloud job IMAGE \
  --credentials production-aws \
  --vm-type g6e.xlarge

Region pinning disables regional failover. Use it only for residency, debugging, quota work, or another explicit constraint.

cloudConfig fields

The generated DeploymentAdmissionInputAnyOf1CloudConfig model exposes the contract fields shown above, plus independent input, output, and checkpoint storage credentials and regions. Use DeploymentAdmissionInput.from_dict() with wire names, or the generated model directly with Python snake-case names. There are no client-level deployment defaults or inheritance helpers.

Bucket credential rules

For Jobs, input, output, and checkpoint storage credentials are independent. When a storage credential is omitted, that Bucket uses compute credentials; setting one Bucket's storage credential does not affect the others.

Service checkpoints always use the selected compute credential. A Service cannot set a separate checkpoint storage credential, although it may set checkpoint_storage_region for a same-identity bucket in another region.

On the CLI, cross-account storage requires a credential and region:

anycloud job IMAGE \
  --credentials compute-account \
  --input-bucket shared-data \
  --input-storage-credentials storage-account \
  --input-storage-region us-east-1

In Python, supply the matching inputStorageCredentialName and inputStorageRegion fields in the generated admission model.

Cross-cloud storage currently supports S3. It uses scoped STS credentials that last up to 36 hours and are not refreshed during periodic sync. VM-hosted workloads mint a fresh token for their final copy. Worker-targeted Jobs do not support per-Job Buckets.

Root disk tiers

Disk capacity and performance are independent. --disk-size 100 --disk-tier high means a 100 GB root disk at the high tier. high is the default.

On AWS, tiers map to gp3 root-volume settings:

Tier	IOPS	Throughput
medium	3,000	125 MiB/s
high	8,000	1,000 MiB/s
ultra	16,000	1,000 MiB/s

AWS reads the selected AMI's root-disk metadata before launch. When disk size is omitted, it raises roots smaller than the capacity required for the requested gp3 IOPS (16 GB for high, 32 GB for ultra) and leaves larger roots unchanged. An explicit size is preserved when valid and rejected if it would shrink the AMI root or fall below the tier's IOPS-to-capacity minimum.

On Azure, medium uses Standard storage; high and ultra use Premium SSD. Azure currently maps ultra to the same Premium tier as high. The VM size must support Premium storage.

On GCP, the root-disk type is machine-aware:

Machine storage class	medium	high	ultra
Persistent Disk	Machine-compatible default	pd-ssd	pd-ssd
Hyperdisk-only	Hyperdisk Balanced defaults	8,000 IOPS / 1,000 MiB/s	16,000 IOPS / 1,000 MiB/s

Leaving --disk-tier unset resolves to the shared high default before the provider request is built. Pass medium explicitly to use the standard tier.

GCP high and ultra intentionally collapse to the same pd-ssd disk class on Persistent Disk machines such as G2. For Hyperdisk high or ultra, omitting --disk-size selects 100 GB. An explicit Hyperdisk size must be at least 16 GB for high or 32 GB for ultra; Anycloud rejects a smaller size instead of silently enlarging it. Known families that require Hyperdisk for fast tiers use Hyperdisk; other families, including newly published ones, optimistically use pd-ssd for high and ultra. In expanded fallback pools, known incompatible disk/VM combinations are removed before target selection; if none remain, Anycloud reports the disk requirement. A fully pinned target stays on the direct provisioning path and GCP reports the same incompatibility as an invalid request there.

The gateway's small Hyperdisk exception list is curated from GCP's supported-disk sections for general-purpose, compute-optimized, memory-optimized, storage-optimized, and accelerator-optimized machines. Those are provider compatibility facts; their mapping to Anycloud's tiers and performance targets is Anycloud policy. GCP's MachineType and DiskType APIs do not expose the machine-to-disk compatibility relationship.

Provisioned Hyperdisk performance is a disk limit, not a guarantee. GCP caps actual performance at the lower of the disk's provisioned target and the VM machine type's limit. Anycloud deliberately sends the tier target unchanged; it does not clamp that target to the selected machine. GCP accepts such a disk even when the machine cannot realize all of its performance, while billing Hyperdisk capacity and provisioned performance separately. Choose a machine whose limits match the tier to avoid paying for performance that the VM cannot use.

Disk tiers are supported on AWS, GCP, and Azure. Other providers reject a non-default tier.

Docker runtime options

CLI	docker_options key	Example
--gpus	gpus	all, 2
--shm-size	shmSize	8g
--memory	memory	32g
--cpus	cpus	4
--ipc	ipc	host
--ulimit	ulimits	repeatable
--runtime	runtime	nvidia
--bind	binds	repeatable host bind

Anycloud configures GPU access automatically for GPU-backed VMs. --gpus controls what Docker exposes; it is not normally necessary to specify an NVIDIA runtime. Explicit --gpus and --runtime nvidia requests are rejected on VMs known to have no NVIDIA GPU, and a numeric --gpus count cannot exceed the resolved VM's GPU count. When a VM reports an accelerator the catalog cannot identify, an explicit --gpus still forces GPU passthrough. With ordered VM fallbacks, Anycloud skips targets that cannot honor the request.

The API validates option names, types, and values before image inspection or provisioning. VM-host targets support the options above and accept the runc and nvidia runtime names. A user bind cannot overlap an enabled Anycloud bucket mount at /mnt/input, /mnt/output, or /mnt/checkpoint.

For Workers, --gpus is a nonnegative Worker GPU count rather than a Docker exposure setting. The Cluster VM type determines the accelerator model and available supply. Positive counts require catalog-verified GPU capacity, cannot exceed its per-VM supply, and become equal Kubernetes requests and limits. Unclassified or unverifiable capacity accepts only explicit zero, which emits no GPU resource. Catalogued CPU Clusters infer zero when omitted and reject positive counts. Workers also translate --shm-size, --memory, and --cpus, while dockerOptions.gpus, IPC, ulimit, runtime, and bind settings are rejected.

Runtime environment

Every workload receives:

Variable	Meaning
DEPLOYMENT_ID	The deployment's unique ID
PORT	Service listen port; defaults to 8088

Workloads with Buckets receive the applicable fixed mount paths /mnt/input, /mnt/output, and /mnt/checkpoint. See Buckets.