> For the complete documentation index, see [llms.txt](https://docs.acecloud.ai/knowledge-base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.acecloud.ai/knowledge-base/cli/caas/deployments.md).

# Deployments

Create, manage, and monitor container deployments on AceCloud CaaS.

***

## List

List all container deployments in the current project.

```bash
ace deployment list
```

**Aliases:** `ls`

**Example output:**

```
NAME                           TYPE       STATUS       IMAGE                     REPLICAS     ENDPOINT
my-app                         shared     Running      nginx:latest              2            https://my-app.example.com
api-server                     dedicated  Running      registry.io/api:v2        3            -
```

***

## Get / Show

Get detailed information about a deployment.

```bash
ace deployment get <deployment-name>
```

**Aliases:** `show`, `describe`

**Example output:**

```
  Name:                    my-app
  Type:                    shared
  Status:                  Running
  Image:                   nginx:latest (public)
  CPU:                     0.5 cores
  Memory:                  512Mi
  Replicas:                2
  External Access:         true
  Endpoint Access:         public
  Ports:
    http: 80 -> 80 (HTTP)
  Public Endpoints:
    https://my-app.example.com
  Created:                 2025-03-20T14:30:00Z
```

***

## Create

Create a new container deployment.

```bash
ace deployment create \
  --name <deployment-name> \
  --image <container-image> \
  [options]
```

### Required Flags

| Flag      | Description                                                       |
| --------- | ----------------------------------------------------------------- |
| `--name`  | Deployment name (3-60 chars, lowercase alphanumeric with hyphens) |
| `--image` | Container image reference (e.g. `nginx:latest`)                   |

### Resource Flags (Shared)

| Flag         | Default | Description                                                  |
| ------------ | ------- | ------------------------------------------------------------ |
| `--cpu`      |         | CPU cores (0.1-16.0, required for shared)                    |
| `--memory`   |         | Memory allocation (e.g. `512Mi`, `1Gi`, required for shared) |
| `--replicas` | `1`     | Number of replicas (1-12)                                    |

### Resource Flags (Dedicated)

| Flag             | Default  | Description                                          |
| ---------------- | -------- | ---------------------------------------------------- |
| `--type`         | `shared` | Deployment type: `shared` or `dedicated`             |
| `--flavor`       |          | Flavor name or UUID (required for dedicated)         |
| `--network-cidr` |          | New network CIDR (e.g. `10.0.0.0/16`, for dedicated) |
| `--network-id`   |          | Existing VPC network UUID (for dedicated)            |

### Networking Flags

| Flag                | Default  | Description                                      |
| ------------------- | -------- | ------------------------------------------------ |
| `--external-access` | `false`  | Enable external access (public endpoint)         |
| `--endpoint-access` | `public` | Endpoint mode: `public` or `protected`           |
| `--cidr`            |          | CIDR blocks for protected endpoints (repeatable) |
| `--x-forwarded-for` | `false`  | Enable X-Forwarded-For header                    |

### Port Flags

Ports can be specified in two ways:

**Single port mode:**

| Flag               | Default | Description                                        |
| ------------------ | ------- | -------------------------------------------------- |
| `--port-name`      |         | Port name (e.g. `http`)                            |
| `--protocol`       | `HTTP`  | Protocol: `HTTP`, `HTTPS`, `TCP`, `UDP`            |
| `--container-port` |         | Container port (1-65535)                           |
| `--exposed-port`   |         | Exposed port (1-65535, defaults to container port) |

**Multi-port mode:**

| Flag     | Description                                                                  |
| -------- | ---------------------------------------------------------------------------- |
| `--port` | Port spec in `name:protocol:containerPort[:exposedPort]` format (repeatable) |

> **Note:** If no port is specified, the CLI automatically adds a default port: `http:HTTP:80:80`.

### Other Flags

| Flag             | Default  | Description                                                                |
| ---------------- | -------- | -------------------------------------------------------------------------- |
| `--env`          |          | Environment variable in `KEY=VALUE` format (repeatable)                    |
| `--volume`       |          | Volume in `name:mountPath:size` format (repeatable, e.g. `data:/data:1Gi`) |
| `--command`      |          | Container command override (repeatable for args)                           |
| `--image-type`   | `public` | Image type: `public` or `private`                                          |
| `--image-secret` |          | Image pull secret for private images (repeatable)                          |

### Autoscaling Flags

| Flag              | Default | Description                                  |
| ----------------- | ------- | -------------------------------------------- |
| `--autoscale`     | `false` | Enable horizontal pod autoscaling            |
| `--autoscale-min` | `1`     | Minimum replicas (1-12)                      |
| `--autoscale-max` | `5`     | Maximum replicas (1-12)                      |
| `--cpu-target`    | `80`    | CPU utilization target percentage (1-100)    |
| `--memory-target` | `80`    | Memory utilization target percentage (1-100) |

### Examples

**Shared deployment with public endpoint:**

```bash
ace deployment create \
  --name my-app \
  --image nginx:latest \
  --cpu 0.5 \
  --memory 512Mi \
  --replicas 1 \
  --external-access \
  --port-name http \
  --protocol HTTP \
  --container-port 80 \
  --exposed-port 80
```

**With environment variables and volumes:**

```bash
ace deployment create \
  --name my-app \
  --image nginx:latest \
  --cpu 1 \
  --memory 1Gi \
  --replicas 2 \
  --env DB_HOST=localhost \
  --env DB_PORT=5432 \
  --volume data:/data:1Gi
```

**With autoscaling:**

```bash
ace deployment create \
  --name my-app \
  --image nginx:latest \
  --cpu 1 \
  --memory 1Gi \
  --replicas 2 \
  --autoscale \
  --autoscale-min 2 \
  --autoscale-max 5 \
  --cpu-target 80 \
  --memory-target 70
```

**Protected endpoint with CIDR whitelist:**

```bash
ace deployment create \
  --name my-app \
  --image nginx:latest \
  --cpu 0.5 \
  --memory 512Mi \
  --external-access \
  --endpoint-access protected \
  --cidr 10.0.0.0/16 \
  --cidr 192.168.0.0/24 \
  --port-name http \
  --protocol HTTP \
  --container-port 80 \
  --exposed-port 80
```

**Multiple ports:**

```bash
ace deployment create \
  --name my-app \
  --image nginx:latest \
  --cpu 0.5 \
  --memory 512Mi \
  --external-access \
  --port http:HTTP:80:80 \
  --port metrics:TCP:9090:9090
```

**Dedicated deployment with new network:**

```bash
ace deployment create \
  --name my-app \
  --type dedicated \
  --image nginx:latest \
  --flavor ACE.CPU.4C16R \
  --replicas 1 \
  --network-cidr 10.0.0.0/16
```

**Dedicated deployment with existing VPC:**

```bash
ace deployment create \
  --name my-app \
  --type dedicated \
  --image nginx:latest \
  --flavor ACE.CPU.4C16R \
  --replicas 1 \
  --network-id <vpc-uuid>
```

**Private image with custom command:**

```bash
ace deployment create \
  --name my-app \
  --image registry.example.com/app:v1 \
  --image-type private \
  --image-secret my-secret \
  --cpu 0.5 \
  --memory 512Mi \
  --command "python" \
  --command "-m" \
  --command "http.server"
```

***

## Update

Update an existing deployment. Only the specified flags are changed; all other fields are preserved from the current deployment state.

```bash
ace deployment update <deployment-name> [flags]
```

The deployment **name** and **type** cannot be changed.

### Updatable Flags

All create flags except `--name` and `--type` can be used with update. Common examples:

```bash
# Scale replicas
ace deployment update my-app --replicas 3

# Update image
ace deployment update my-app --image nginx:1.25

# Change resources
ace deployment update my-app --cpu 1.0 --memory 1Gi

# Enable autoscaling
ace deployment update my-app --autoscale --autoscale-min 2 --autoscale-max 5

# Update environment variables (replaces all existing)
ace deployment update my-app --env NEW_VAR=value --env DB_HOST=newhost

# Change endpoint access
ace deployment update my-app --endpoint-access public

# Update ports
ace deployment update my-app --port http:HTTP:8080:8080
```

> **Important:** When updating `--env`, `--volume`, or `--command`, the new values **replace** all existing values. Make sure to include all desired values in the update command.

***

## Delete

Delete one or more deployments.

```bash
ace deployment delete <deployment-name> [deployment-name...]
```

**Aliases:** `rm`

**Examples:**

```bash
# Delete single deployment
ace deployment delete my-app

# Delete multiple deployments
ace deployment delete my-app api-server worker
```

***

## Restart

Restart all pods in a deployment (rolling restart).

```bash
ace deployment restart <deployment-name>
```

**Example:**

```bash
ace deployment restart my-app
```

***

## Replicas

List the individual replica pods for a deployment.

```bash
ace deployment replicas <deployment-name>
```

**Aliases:** `pods`

**Example output:**

```
Replicas (3):
  my-app-7d8f6b5c9-abc12
  my-app-7d8f6b5c9-def34
  my-app-7d8f6b5c9-ghi56
```

***

## Global Flags

| Flag            | Description                                |
| --------------- | ------------------------------------------ |
| `-o, --output`  | Output format: `table` (default) or `json` |
| `-v, --verbose` | Show full JSON request/response            |
| `--project`     | Override project ID                        |
| `--region`      | Override region                            |