v1

Single containers

Create and start a single container

This endpoint creates and starts a single container in your space based on the Docker image that is specified in the Image field of the request json. A single container in IBM Containers is similar to a container that you create in your local Docker environment. Single containers are a good way to start with IBM Containers and to learn about how containers work in the IBM Cloud and the features that IBM Containers provides. They are also recommended when you want to run simple app tests or during the development process of an app.

In the Docker API there are two separate APIs to create and start a container. However in IBM Containers a container is created and started in a single API call. Therefore, this API merges parameters from the Docker API to create and start container.

To create a container with IBM Containers, you must at least define the image that the container is based on.

Image: You must include the full path to the image in your private Bluemix registry in the format: registry.ng.bluemix.net/<namespace>/<image>.

post/containers/create

Query parameters

namestring

Choose a name for your container. The characters in the name can include uppercase letters, lowercase letters, numbers, periods (.), underscores (_), or hyphens (-), but the name must start with a letter.

Headers

X-Auth-Tokenstring required

The Bluemix JSON web token that you receive when logging into Bluemix. Run cf oauth-token to retrieve your access token.

X-Auth-Project-Idstring required

The unique ID of your organization space where you want to create or work with your containers. Run cf space <space_name> --guid, where <space_name> is the name of your space, to retrieve your space ID.

Request body

BluemixAppstring

The name of the Cloud Foundry app that you want to bind to your container. The Cloud Foundry app must be created in the same space where you want to create your container.

Cmdstring[]

The command and arguments in this list are passed to the container to be executed when the container is started. This command must be a long-running command. Do not use a short-lived command, for example, /bin/date, because it might cause the container to crash. <br>Sample long-running commands:<br>["ping","localhost"]<br>["tail","-f","/dev/null"]<br>["sh","-c","while true; do date; sleep 20; done"]

Cpusetstring

Pins the container processes to a specific CPU core on the compute host. For example: 0 means that processes are executed on the first core only.

Envstring[]

A list of environment variables in the form of key=value pairs. All keys in this list have to be unique. List multiple keys separately and if you include quotation marks, include them around both the environment variable name and the value.

ExposedPortsstring[]

All public ports that need to be exposed for the container, so the container can be accessed from the Internet.

Imagestring required

Full path to the image in your private Bluemix registry in the format registry.ng.bluemix.net/namespace/image.

Memoryinteger

The container memory that is set for the container in Megabyte. Choose one of the following sizes: Pico 64 MB, Nano 128 MB, Micro 256 MB, Tiny 512 MB, Small 1 GB (1024 MB), Medium 2 GB (2048 MB), Large 4 GB (4096 MB) XLarge 8GB (8192 MB) and 2XLarge 16 GB (16384 MB).

NumberCpusinteger

Number of virtual CPUs that are allocated to the container.

Volumesstring

Mount a volume to a container by specifying the details in the following format: VOLUME_NAME:/DIRECTORY_PATH[:ro]. Example: testvolume:/volumedata/temp:rw. By default, all volumes will be set up with read-write access inside the container (rw). If you wish to set up your volume with read-only access, enter ro. Note: To mount a volume to a container, you must create the volume in your space first by using the cf ic volume-create command, or calling the POST /volumes/create endpoint.

Response

OK. The creation of a single container with the specified attributes has been initiated.

Idstring

Unique ID representing a container.

flavor_idinteger

The ID of the container size.

meminteger

The amount of container memory that has been assigned to the container. If the container memory was not specified in the API request, a container with 64 Megabyte container memory is created by default.

vcpuinteger

Number of virtual CPUs that are assigned to the container.