Zum Hauptinhalt springen

Create, update or delete Services or Volumes belonging to a Stack

PATCH/v2/stacks/{stackId}
API-Version
v2
Request-Methode
PATCH
Operation-ID
container-update-stack

This command can be used to modify the desired state of a container stack.

Usage​

Obtaining the default stack​

Every mStudio project comes with a default stack named default. You can obtain the default stack by using the unknown operation container-list-stack operation.

Creating new stacks​

Creating new stacks is not supported at this time. You can only manage the default stack.

Deleting containers/services from an existing stack​

Since this is a differential PATCH operation, omitting a service from the request body will simply leave any existing services unchanged.

Instead, to remove an existing container from a stack, set it to an empty object {} in the request body. This will remove the container from the stack.

PATCH /v2/stacks/{stackId} HTTP/1.1
Host: api.mittwald.de
Content-Type: application/json

{
  "services": {
    "mysql": {}
  }
}

Managing volumes​

You have two options for managing storage for your container stacks:

  • Explicitly declare volumes, using the $.volumes property of this request. Volumes are referenced by name, and can be mounted into the container by referencing them in the $.services[*].volumes property in the format <volume-name>:<mount-path>.
  • Use the project volume; this volume is shared among all managed apps and containers of a project. In order to mount the project volume, specify a file path instead of a volume name when mounting the volume (example /home/p-XXXXX/html:/var/html).

Request​

  • stackIdstring (uuid)required

    ID of the Stack to create, update or delete Services or Volumes for.

Responses​

Format
application/json
Beschreibung

OK

  • descriptionstringrequired
  • disabledbooleanrequired
  • idstring (uuid)required
  • prefixstringrequired

    Generated, immutable identifier of the Stack (e.g. st-XXXXXX). Managed apps in the same project can resolve a container of this Stack as <serviceName>.<prefix>; containers of the same Stack can use the service name alone, and containers of other Stacks cannot communicate with it. The prefix is also the directory of the Stack's service log files (/var/log/container/<prefix>/ in the project file system).

  • projectIdstring (uuid)required
  • servicesArray von object

    A set of containers that should be started in this stack. The key is relevant for network connectivity between containers, because you can use it as DNS name to resolve this containers from other containers running in the same project (or from managed apps running in the same project). To delete an existing container from a stack using a PUT request, simply omit it from the request body. Using a PATCH request, set it to an empty object {}.

    • Array[
      • *object
        • deployobject
          • resourcesobject
            • limits
              • cpusstring

                CPU limit for the container. The value can be specified as a decimal number, where 1 corresponds to one full CPU core. For example, 0.5 means that the container is limited to using half of a CPU core.

              • memorystring

                Memory limit for the container, as an integer followed by a unit, similar to the byte values used by Docker Compose‍: b (bytes), k or kb (kilobytes), m or mb (megabytes) and g or gb (gigabytes). Units must be lowercase and are decimal (1g = 1,000,000,000 bytes). A number without a unit is not accepted.

        • deployedStateobjectrequired

          The actual state of the container that is currently deployed.

          • commandArray von string

            The container command (equivalent to the Docker cmd‍). When omitted, this defaults to the command defined in the image.

            • Array[
              • *string
              ]
          • entrypointArray von string

            The container entrypoint (equivalent to the Docker entrypoint‍). When omitted, this defaults to the entrypoint defined in the image.

            • Array[
              • *string
              ]
          • envsobject

            Key-value map of environment variables that should be passed into the container.

            • *string
          • imagestringrequired

            The image to run, in the usual format also used by docker run and docker compose. When the image is pulled from a private registry, make sure to create it first, using the container-create-registry endpoint. The appropriate registry is matched by hostname.

          • imageDigeststring

            The digest of the image that is currently deployed.

          • portsArray von string

            Exposed ports. Follows the format <public-port>:<container-port>/<protocol>. Exposed ports can be accessed from other containers (or managed apps) within the same project. To expose a port publicly, connect it with an ingress resource.

            • Array[
              • *string
              ]
          • volumesArray von string

            Volume mounts for this container. These items always follow the format <volume>:<mountpoint>. The <volume> may either be a named volume, or a file path in the (always present) project file system (which is shared among containers and managed apps within a project).

            • Array[
              • *string
              ]
        • descriptionstringrequired
        • idstring (uuid)required
        • messagestring

          Message explaining the current state of the container. This may contain information about the current state of the container, or errors that occurred during deployment.

        • pendingStateobjectrequired

          The desired state that is waiting to be reconciled.

          • commandArray von string

            The container command (equivalent to the Docker cmd‍). When omitted, this defaults to the command defined in the image.

            • Array[
              • *string
              ]
          • entrypointArray von string

            The container entrypoint (equivalent to the Docker entrypoint‍). When omitted, this defaults to the entrypoint defined in the image.

            • Array[
              • *string
              ]
          • envsobject

            Key-value map of environment variables that should be passed into the container.

            • *string
          • imagestringrequired

            The image to run, in the usual format also used by docker run and docker compose. When the image is pulled from a private registry, make sure to create it first, using the container-create-registry endpoint. The appropriate registry is matched by hostname.

          • imageDigeststring

            The digest of the image that is currently deployed.

          • portsArray von string

            Exposed ports. Follows the format <public-port>:<container-port>/<protocol>. Exposed ports can be accessed from other containers (or managed apps) within the same project. To expose a port publicly, connect it with an ingress resource.

            • Array[
              • *string
              ]
          • volumesArray von string

            Volume mounts for this container. These items always follow the format <volume>:<mountpoint>. The <volume> may either be a named volume, or a file path in the (always present) project file system (which is shared among containers and managed apps within a project).

            • Array[
              • *string
              ]
        • requiresRecreatebooleanrequired
        • restartPolicystring (einer von: no, always, on-failure, unless-stopped)

          Restart policy of the container. unless-stopped currently behaves like on-failure.

        • serviceNamestringrequired
        • shortIdstringrequired

          A short ID of the container. This is a unique identifier for the container within the project, and can be used to reference it in other API calls, or for SSH connections.

        • statusstring (einer von: running, stopped, error, creating, starting, stopping, unspecified)required

          Status of a Service. creating: the Service was declared and has not reported a status yet. starting: the container is being started. running: the container is ready. stopping: the container is being stopped or terminated. stopped: the container was stopped or has exited. error: the container or its image is in an error state; see the Service's message for details. unspecified: the cluster currently reports no decisive condition for the container.

        • statusSetAtstring (date-time)required
        • templateIdstring

          ID of the template used to create this service, if one was used.

      ]
  • templateIdstring

    Id of the Template used to create this stack, if one was used.

  • updateScheduleobject
    • cronstringrequired
    • timezonestring
  • volumesArray von object
    • Array[
      • *object
        • idstring (uuid)required
        • linkedServicesArray von string (uuid)
          • Array[
            • *string (uuid)
            ]
        • namestringrequired
        • orphanedbooleanrequired

          Whether no service of the Stack mounts this Volume. An orphaned Volume still belongs to its Stack and keeps its data until it is deleted explicitly using DELETE /v2/stacks/{stackId}/volumes/{volumeId}.

        • stackIdstring (uuid)required
        • storageUsageInBytesinteger (int64)required
        • storageUsageInBytesSetAtstring (date-time)required
      ]
Content-Type: application/json

{
  "description": "string",
  "disabled": true,
  "id": "f0f86186-0a5a-45b2-aa33-502777496347",
  "prefix": "string",
  "projectId": "f0f86186-0a5a-45b2-aa33-502777496347",
  "services": [
    {
      "deploy": {
        "resources": {
          "limits": {
            "cpus": "0.5",
            "memory": "1gb"
          }
        }
      },
      "deployedState": {
        "command": [
          "mysqld",
          "mysqld"
        ],
        "entrypoint": [
          "docker-entrypoint.sh",
          "docker-entrypoint.sh"
        ],
        "envs": {
          "MYSQL_DATABASE": "my_db",
          "MYSQL_PASSWORD": "my_password",
          "MYSQL_ROOT_PASSWORD": "my_root_password",
          "MYSQL_USER": "my_user"
        },
        "image": "mysql:8.0",
        "imageDigest": "string",
        "ports": [
          "3306/tcp",
          "3306:3306/tcp"
        ],
        "volumes": [
          "data:/var/lib/mysql",
          "/home/p-XXXXX/html:/var/www",
          "data:/var/lib/mysql",
          "/home/p-XXXXX/html:/var/www"
        ]
      },
      "description": "MySQL DB",
      "id": "f0f86186-0a5a-45b2-aa33-502777496347",
      "message": "Container ready",
      "pendingState": {
        "command": [
          "mysqld",
          "mysqld"
        ],
        "entrypoint": [
          "docker-entrypoint.sh",
          "docker-entrypoint.sh"
        ],
        "envs": {
          "MYSQL_DATABASE": "my_db",
          "MYSQL_PASSWORD": "my_password",
          "MYSQL_ROOT_PASSWORD": "my_root_password",
          "MYSQL_USER": "my_user"
        },
        "image": "mysql:8.0",
        "imageDigest": "string",
        "ports": [
          "3306/tcp",
          "3306:3306/tcp"
        ],
        "volumes": [
          "data:/var/lib/mysql",
          "/home/p-XXXXX/html:/var/www",
          "data:/var/lib/mysql",
          "/home/p-XXXXX/html:/var/www"
        ]
      },
      "requiresRecreate": true,
      "restartPolicy": "always",
      "serviceName": "mysql-db",
      "shortId": "c-XXXXXX",
      "status": "running",
      "statusSetAt": "1985-10-26T01:21:00.000Z",
      "templateId": "string"
    }
  ],
  "templateId": "string",
  "updateSchedule": {
    "cron": "string",
    "timezone": "string"
  },
  "volumes": [
    {
      "id": "f0f86186-0a5a-45b2-aa33-502777496347",
      "linkedServices": [
        "f0f86186-0a5a-45b2-aa33-502777496347"
      ],
      "name": "string",
      "orphaned": true,
      "stackId": "f0f86186-0a5a-45b2-aa33-502777496347",
      "storageUsageInBytes": 123,
      "storageUsageInBytesSetAt": "1985-10-26T01:21:00.000Z"
    }
  ]
}
{
  "properties": {
    "description": {
      "type": "string"
    },
    "disabled": {
      "type": "boolean"
    },
    "id": {
      "format": "uuid",
      "type": "string"
    },
    "prefix": {
      "description": "Generated, immutable identifier of the Stack (e.g. `st-XXXXXX`). Managed apps in the same project can resolve a container of this Stack as `<serviceName>.<prefix>`; containers of the same Stack can use the service name alone, and containers of other Stacks cannot communicate with it. The prefix is also the directory of the Stack's service log files (`/var/log/container/<prefix>/` in the project file system).\n",
      "type": "string"
    },
    "projectId": {
      "format": "uuid",
      "type": "string"
    },
    "services": {
      "items": {
        "properties": {
          "deploy": {
            "properties": {
              "resources": {
                "properties": {
                  "limits": {
                    "properties": {
                      "cpus": {
                        "description": "CPU limit for the container. The value can be specified as a decimal number, where `1` corresponds to\none full CPU core. For example, `0.5` means that the container is limited to using half of a CPU core.\n",
                        "example": "0.5",
                        "type": "string"
                      },
                      "memory": {
                        "description": "Memory limit for the container, as an integer followed by a unit, similar to the [byte values used by Docker Compose](https://docs.docker.com/reference/compose-file/extension/#specifying-byte-values): `b` (bytes), `k` or `kb` (kilobytes), `m` or `mb` (megabytes) and `g` or `gb` (gigabytes). Units must be lowercase and are decimal (`1g` = 1,000,000,000 bytes). A number without a unit is not accepted.\n",
                        "example": "1gb",
                        "type": "string"
                      }
                    }
                  }
                },
                "type": "object"
              }
            },
            "type": "object"
          },
          "deployedState": {
            "description": "The actual state of the container that is currently deployed.\n",
            "properties": {
              "command": {
                "description": "The container command (equivalent to the [Docker cmd](https://docs.docker.com/reference/dockerfile/#cmd)). When omitted, this defaults to the command defined in the image.\n",
                "example": [
                  "mysqld",
                  "mysqld"
                ],
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "entrypoint": {
                "description": "The container entrypoint (equivalent to the [Docker entrypoint](https://docs.docker.com/reference/dockerfile/#entrypoint)). When omitted, this defaults to the entrypoint defined in the image.\n",
                "example": [
                  "docker-entrypoint.sh",
                  "docker-entrypoint.sh"
                ],
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "envs": {
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Key-value map of environment variables that should be passed into the container.\n",
                "example": {
                  "MYSQL_DATABASE": "my_db",
                  "MYSQL_PASSWORD": "my_password",
                  "MYSQL_ROOT_PASSWORD": "my_root_password",
                  "MYSQL_USER": "my_user"
                },
                "type": "object"
              },
              "image": {
                "description": "The image to run, in the usual format also used by `docker run` and `docker compose`. When the image is pulled from a private registry, make sure to create it first, using the `container-create-registry` endpoint. The appropriate registry is matched by hostname.\n",
                "example": "mysql:8.0",
                "type": "string"
              },
              "imageDigest": {
                "description": "The digest of the image that is currently deployed.\n",
                "type": "string"
              },
              "ports": {
                "description": "Exposed ports. Follows the format `<public-port>:<container-port>/<protocol>`. Exposed ports can be accessed from other containers (or managed apps) within the same project. To expose a port publicly, connect it with an ingress resource.\n",
                "example": [
                  "3306/tcp",
                  "3306:3306/tcp"
                ],
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "volumes": {
                "description": "Volume mounts for this container. These items always follow the format `<volume>:<mountpoint>`. The `<volume>` may either be a named volume, or a file path in the (always present) project file system (which is shared among containers and managed apps within a project).\n",
                "example": [
                  "data:/var/lib/mysql",
                  "/home/p-XXXXX/html:/var/www",
                  "data:/var/lib/mysql",
                  "/home/p-XXXXX/html:/var/www"
                ],
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            },
            "required": [
              "image"
            ],
            "type": "object"
          },
          "description": {
            "example": "MySQL DB",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "message": {
            "description": "Message explaining the current state of the container. This may contain information about the current state of the container, or errors that occurred during deployment.\n",
            "example": "Container ready",
            "type": "string"
          },
          "pendingState": {
            "description": "The desired state that is waiting to be reconciled.\n",
            "properties": {
              "command": {
                "description": "The container command (equivalent to the [Docker cmd](https://docs.docker.com/reference/dockerfile/#cmd)). When omitted, this defaults to the command defined in the image.\n",
                "example": [
                  "mysqld",
                  "mysqld"
                ],
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "entrypoint": {
                "description": "The container entrypoint (equivalent to the [Docker entrypoint](https://docs.docker.com/reference/dockerfile/#entrypoint)). When omitted, this defaults to the entrypoint defined in the image.\n",
                "example": [
                  "docker-entrypoint.sh",
                  "docker-entrypoint.sh"
                ],
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "envs": {
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Key-value map of environment variables that should be passed into the container.\n",
                "example": {
                  "MYSQL_DATABASE": "my_db",
                  "MYSQL_PASSWORD": "my_password",
                  "MYSQL_ROOT_PASSWORD": "my_root_password",
                  "MYSQL_USER": "my_user"
                },
                "type": "object"
              },
              "image": {
                "description": "The image to run, in the usual format also used by `docker run` and `docker compose`. When the image is pulled from a private registry, make sure to create it first, using the `container-create-registry` endpoint. The appropriate registry is matched by hostname.\n",
                "example": "mysql:8.0",
                "type": "string"
              },
              "imageDigest": {
                "description": "The digest of the image that is currently deployed.\n",
                "type": "string"
              },
              "ports": {
                "description": "Exposed ports. Follows the format `<public-port>:<container-port>/<protocol>`. Exposed ports can be accessed from other containers (or managed apps) within the same project. To expose a port publicly, connect it with an ingress resource.\n",
                "example": [
                  "3306/tcp",
                  "3306:3306/tcp"
                ],
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "volumes": {
                "description": "Volume mounts for this container. These items always follow the format `<volume>:<mountpoint>`. The `<volume>` may either be a named volume, or a file path in the (always present) project file system (which is shared among containers and managed apps within a project).\n",
                "example": [
                  "data:/var/lib/mysql",
                  "/home/p-XXXXX/html:/var/www",
                  "data:/var/lib/mysql",
                  "/home/p-XXXXX/html:/var/www"
                ],
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            },
            "required": [
              "image"
            ],
            "type": "object"
          },
          "requiresRecreate": {
            "type": "boolean"
          },
          "restartPolicy": {
            "description": "Restart policy of the container. `unless-stopped` currently behaves like `on-failure`.\n",
            "enum": [
              "no",
              "always",
              "on-failure",
              "unless-stopped"
            ],
            "example": "always",
            "type": "string"
          },
          "serviceName": {
            "example": "mysql-db",
            "type": "string"
          },
          "shortId": {
            "description": "A short ID of the container. This is a unique identifier for the container within the project, and can be used to reference it in other API calls, or for SSH connections.\n",
            "example": "c-XXXXXX",
            "type": "string"
          },
          "status": {
            "description": "Status of a Service. `creating`: the Service was declared and has not reported a status yet. `starting`: the container is being started. `running`: the container is ready. `stopping`: the container is being stopped or terminated. `stopped`: the container was stopped or has exited. `error`: the container or its image is in an error state; see the Service's `message` for details. `unspecified`: the cluster currently reports no decisive condition for the container.\n",
            "enum": [
              "running",
              "stopped",
              "error",
              "creating",
              "starting",
              "stopping",
              "unspecified"
            ],
            "type": "string"
          },
          "statusSetAt": {
            "format": "date-time",
            "type": "string"
          },
          "templateId": {
            "description": "ID of the template used to create this service, if one was used.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "stackId",
          "projectId",
          "description",
          "serviceName",
          "pendingState",
          "deployedState",
          "status",
          "shortId",
          "statusSetAt",
          "requiresRecreate"
        ],
        "type": "object"
      },
      "type": "array",
      "description": "A set of containers that should be started in this stack. The key is relevant for network connectivity between containers, because you can use it as DNS name to resolve this containers from other containers running in the same project (or from managed apps running in the same project).\nTo **delete** an existing container from a stack using a `PUT` request, simply omit it from the request body. Using a `PATCH` request, set it to an empty object `{}`.\n",
      "x-example-key": "mysql"
    },
    "templateId": {
      "description": "Id of the Template used to create this stack, if one was used.",
      "type": "string"
    },
    "updateSchedule": {
      "nullable": true,
      "properties": {
        "cron": {
          "type": "string"
        },
        "timezone": {
          "type": "string"
        }
      },
      "required": [
        "cron"
      ],
      "type": "object"
    },
    "volumes": {
      "items": {
        "properties": {
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "linkedServices": {
            "items": {
              "format": "uuid",
              "type": "string"
            },
            "type": "array"
          },
          "name": {
            "type": "string"
          },
          "orphaned": {
            "description": "Whether no service of the Stack mounts this Volume. An orphaned Volume still belongs to its Stack and keeps its data until it is deleted explicitly using `DELETE /v2/stacks/{stackId}/volumes/{volumeId}`.\n",
            "type": "boolean"
          },
          "stackId": {
            "format": "uuid",
            "type": "string"
          },
          "storageUsageInBytes": {
            "format": "int64",
            "type": "integer"
          },
          "storageUsageInBytesSetAt": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "stackId",
          "name",
          "orphaned",
          "storageUsageInBytes",
          "storageUsageInBytesSetAt"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "id",
    "projectId",
    "description",
    "disabled",
    "prefix"
  ],
  "type": "object"
}

Nutzungsbeispiele​

$ curl \
    --fail \
    --location \
    -X PATCH \
    -d '{"services":{"mysql":{"command":["mysqld"],"deploy":{"resources":{"limits":{"cpus":"0.5","memory":"1gb"}}},"entrypoint":["docker-entrypoint.sh"],"environment":{"MYSQL_DATABASE":"my_db","MYSQL_PASSWORD":"my_password","MYSQL_ROOT_PASSWORD":"my_root_password","MYSQL_USER":"my_user"},"image":"mysql:8.0","ports":["3306/tcp"],"restart":"always","volumes":["data:/var/lib/mysql","/home/p-XXXXX/html:/var/www","/home/p-XXXXX/html:/var/www"],"x-description":"MySQL DB"}},"volumes":{"data":{"name":"mysql-volume"}},"x-description":"uptime kuma","x-update-schedule":{"cron":"* * * * *","timezone":"Europe/Berlin"}}' \
    -H "Authorization: Bearer $MITTWALD_API_TOKEN" \
    -H 'Content-Type: application/json' \
    https://api.mittwald.de/v2/stacks/f0f86186-0a5a-45b2-aa33-502777496347?recreate=true
import { MittwaldAPIV2Client } from "@mittwald/api-client";
import { assertStatus } from "@mittwald/api-client-commons";
  
const client = MittwaldAPIClient.newWithToken(process.env.MITTWALD_API_TOKEN);
const response = await client.container.updateStack({
  "stackId": "f0f86186-0a5a-45b2-aa33-502777496347",
  "data": {
    "services": {
      "mysql": {
        "command": [
          "mysqld"
        ],
        "deploy": {
          "resources": {
            "limits": {
              "cpus": "0.5",
              "memory": "1gb"
            }
          }
        },
        "entrypoint": [
          "docker-entrypoint.sh"
        ],
        "environment": {
          "MYSQL_DATABASE": "my_db",
          "MYSQL_PASSWORD": "my_password",
          "MYSQL_ROOT_PASSWORD": "my_root_password",
          "MYSQL_USER": "my_user"
        },
        "image": "mysql:8.0",
        "ports": [
          "3306/tcp"
        ],
        "restart": "always",
        "volumes": [
          "data:/var/lib/mysql",
          "/home/p-XXXXX/html:/var/www",
          "/home/p-XXXXX/html:/var/www"
        ],
        "x-description": "MySQL DB"
      }
    },
    "volumes": {
      "data": {
        "name": "mysql-volume"
      }
    },
    "x-description": "uptime kuma",
    "x-update-schedule": {
      "cron": "* * * * *",
      "timezone": "Europe/Berlin"
    }
  },
  "queryParameters": {
    "recreate": true
  }
});

assertStatus(response, 200);
  
use \Mittwald\ApiClient\Generated\V2\Clients\Container\UpdateStack\UpdateStackRequest;
use \Mittwald\ApiClient\Generated\V2\Clients\Container\UpdateStack\UpdateStackRequestBody;
  
$client = MittwaldAPIClient::newWithToken(getenv('MITTWALD_API_TOKEN'));

// TODO: Please consult the properties and constructor signature of
// UpdateStackRequestBody to learn how to construct a valid instance
$body = new UpdateStackRequestBody(/* TODO: ... */);

$request = (new UpdateStackRequest(
  stackId: "f0f86186-0a5a-45b2-aa33-502777496347",
  body: $body
))
  ->withRecreate(true);
$response = $client->container()->updateStack($request);

var_dump($response->getBody();

Auf dieser Seite