# 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                            |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.acecloud.ai/knowledge-base/cli/caas/deployments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.