3 Managing Your Docker Environment with Oracle Container Cloud Service
Learn how to manage and monitor your Docker environment using Oracle Container Cloud Service.
Topics
-
Accessing the Container Console for Oracle Container Cloud Service
-
Managing Application Stacks with Oracle Container Cloud Service
-
Managing Docker Containers with Oracle Container Cloud Service
-
Managing Docker Registries with Oracle Container Cloud Service
-
Monitoring Tasks, Events, and Status Updates with Oracle Container Cloud Service
-
Managing Profile Settings with Oracle Container Cloud Service
-
Using Template Functions and Arguments with Oracle Container Cloud Service
Typical Workflow for Managing and Monitoring Your Docker Environment with Oracle Container Cloud Service
Here’s a typical workflow showing the tasks you’ll usually perform to manage your Docker environment using Oracle Container Cloud Service.
You can perform the tasks using the Oracle Container Cloud Service Container Console or the Oracle Container Cloud Service REST API.
Task | Description | More Information |
---|---|---|
Prepare Oracle Container Cloud Service to manage your Docker environment |
|
Creating a Service with Oracle Container Cloud Service Managing Entries in the Service Discovery Database to Enable Container Communication |
Launch containers in the Docker environment |
|
|
(optional) Manage the Docker environment |
|
Managing Services with Oracle Container Cloud Service Managing Application Stacks with Oracle Container Cloud Service Managing Docker Registries with Oracle Container Cloud Service Stopping and Re-starting Service and Stack Deployments Moving Hosts Between Resource Pools Scaling a Running Deployment with Oracle Container Cloud Service |
(optional) Monitor the Docker environment |
|
Monitoring Tasks, Events, and Status Updates |
Accessing the Container Console for Oracle Container Cloud Service
If you’re responsible for managing your Docker environment using Oracle Container Cloud Service, you’ll be using the Container Console.
A Quick Tour of the Container Console
Oracle Container Cloud Service’s Container Console provides graphical dashboards, editors, and views for you to manage the images, containers, and registries in your Docker environment. Take a minute to learn how and where to find what you need.
Here’s what you see on your Container Console Dashboard page when you get started:
Description of the illustration occs_quick-tour-dashboard-1.png
-
Detailed health check panels for Deployments, Hosts, and Resource Pools (2) displaying their status.
-
Summary panels for Services, Stacks, Deployments, Resource Pools, Containers, Images, and Hosts (3) showing the number of each type of object currently being managed by Oracle Container Cloud Service
Click Quick Start Wizard (4) for a shortcut way to set up and deploy services and stacks as Docker containers.
-
Use the Search page (5) to locate any of the objects managed by Oracle Container Cloud Service by searching on their name.
-
Use the Tasks & Events page (6) to monitor the Docker environment by viewing tasks, events, and status updates.
-
Use the Services page (7) and the Stacks page (8) to create new services and stacks of services, and to deploy and manage the services and stacks you’ve created as well as the pre-configured services and stacks that come with Oracle Container Cloud Service.
-
Use the Deployments page (9) to manage and monitor deployed services and stacks, scale a running deployment, and stop and re-start deployments.
-
Use the Containers page (10) to manage and monitor the Docker containers started when you deploy a service or stack, and to view the log files of running containers.
-
Use the Images page (11) to manage Docker images that have been pulled from public or private Docker registries for a deployment, and to start containers directly from images.
-
Use the Hosts page (12) to monitor the status of Oracle Compute virtual machines (‘worker nodes’) running containers for services and stacks you’ve deployed, and to move hosts between resource pools.
-
Use the Resource Pools page (13) to organize hosts and combine them into isolated groups of compute resources.
-
Use the Registries page (14) to define public or private Docker registries from which you want Oracle Container Cloud Service to pull Docker images.
-
Use the Tags page (15) to categorize and organize resource pools and the hosts within them.
-
Use the Service Discovery page (16) to view, update, and add service DNS information in the Service Discovery database to enable running containers to communicate with each other.
The branding bar appears at the top of every Container Console page:
-
Click Settings (17) to change your profile and password, backup the current configuration to a file, and restore the configuration from a previous backup file.
-
Click Get Help (18) to access resources to assist you with your current task, including videos, step-by-step tutorials, and context-sensitive help on the current Container Console page.
Using the Oracle Container Cloud Service Dashboard
When you sign in to Oracle Container Cloud Service, you see the Container Console Dashboard page.
Using the Oracle Container Cloud Service Quick Start Wizard
Find out how to use the Oracle Container Cloud Service Quick Start Wizard to set up and deploy services (based on a single Docker image) and stacks of services (based on multiple different Docker images) as Docker containers.
Searching Oracle Container Cloud Service
You can locate objects managed by Oracle Container Cloud Service using the Container Console Search page.
Description of the illustration occs_search-1.png
Use the Search page as a quick way to find and manage:
-
services
-
stacks
-
deployments
-
containers
-
images
-
hosts
-
resource pools
-
registries
Managing Resource Pools with Oracle Container Cloud Service
Learn about resource pools, how to create them, and how to manage them.
About Resource Pools
Resource pools are a way to organize hosts and combine them into isolated groups of compute resources. Resource pools enable you to manage your Docker environment more effectively by deploying services and stacks efficiently across multiple hosts.
Using resource pools, you can logically define locality as well as a grouping for hosts that share a usage or purpose.
It’s important to note that a host can only exist in one resource pool at a time.
-
default
-
Development
-
Production
Managing Hosts with Oracle Container Cloud Service
Learn about hosts, how to manage them, and how to move them between resource pools.
About Hosts
Hosts (or ‘worker nodes’) are the Oracle Compute virtual machines (VMs) managed by Oracle Container Cloud Service on which you deploy services and stacks to run Docker containers.
Every Oracle Container Cloud Service instance has one manager node, and a number of worker nodes (the ‘hosts’). Oracle Container Cloud Service software running on the manager node orchestrates the deployment of Docker containers to the worker nodes in the instance. Each worker node runs an Oracle Container Cloud Service agent to communicate Docker status to and from the manager node.
A worker node is considered active if the agent can successfully communicate with the manager node. If communication between the manager node and the agent on the worker node is lost for more than a minute or so (due to network, hardware, or software issues), the worker node is considered inactive.
You organize the hosts available to you into resource pools to accommodate your workflow, typically grouping together hosts that share a usage or purpose. It’s important to note that a host can only exist in one resource pool at a time. See About Resource Pools.
Using the Oracle Container Cloud Service Container Console, you can monitor the runtime status of a host (active or inactive). You also use the Container Console to manage the containers running on a host and the images downloaded to it, and to move hosts between resource pools.
Managing Hosts
Find out how to manage and monitor a host and the Docker containers and images on it.
Moving Hosts Between Resource Pools
Find out how to move hosts between resource pools.
If you move a host from one pool to another, any running containers on the host you move are killed. Provided the original pool has resources available, Oracle Container Cloud Service will start new containers for the killed services on a different host in the original pool.
To move hosts between resource pools using the Oracle Container Cloud Service Container Console:
Managing Services with Oracle Container Cloud Service
Learn about services, how to create them, and how to manage them.
About Services
An Oracle Container Cloud Service service comprises all of the necessary configuration for running a Docker image as a container on a host, plus default deployment directives.
Note that services themselves are neither containers nor images running in containers. Services are high-level configuration objects that you can create, deploy, and manage using Oracle Container Cloud Service. You could think of a service as a container ‘template’, or as a set of instructions to follow to deploy a running container.
-
by picking options from a list
-
by copying and pasting a
docker run
command -
by copying and pasting YAML code
Managing Services
You manage both services you’ve created and pre-configured services that come with Oracle Container Cloud Service using the Oracle Container Cloud Service Container Console.
Creating a Service with Oracle Container Cloud Service
You can create a new service using the Oracle Container Cloud Service Container Console. The new service will comprise all of the necessary configuration for running a Docker container on a host, plus default deployment options.
Configuring the Default Orchestration Policy for a Service with Oracle Container Cloud Service
A service’s orchestration policy determines the number of Docker containers to run, and how and where to deploy them.
You can configure a service’s orchestration policy:
-
By specifying default orchestration policy details when you create the service. The default details you specify are used as the default values for the service’s orchestration policy when you deploy the service. See Creating a Service with Oracle Container Cloud Service.
-
By overriding default orchestration policy details with deployment-specific details when you deploy the service. See Deploying a Service with Oracle Container Cloud Service.
Deploying a Service with Oracle Container Cloud Service
You can deploy a service individually rather than as part of a stack (for example, when an application comprises a single service, or a number of services running separately).
Service Configuration Option Reference
Learn about the service configuration options available in the Oracle Container Cloud Service’s Service Editor to manage your Docker environment.
-
use the Builder tab to select configuration options using checkbox and dropdown lists
-
use the Docker Run tab to enter Docker commands directly
-
use the YAML tab to enter YAML commands directly
Builder tab Option | Docker Run equivalent (click to see Docker documentation) | YAML equivalent | Use to: |
---|---|---|---|
DNS | --dns=[ ] | dns | Specify a custom set of DNS servers for the container to use. |
Labels | --label=[ ] | labels | Specify one or more labels for use by Docker Engine. |
Environment Variables | -e=[ ] | environment | Specify the name and value of one or more environment variables. |
Volumes | -v=[ ] | volumes | Specify the desired host, mount point and container target along with its read/write options. |
Volumes From | --volumes-from=[ ] | volumes_from | Specify a comma-delimited list of container-IDs with an optional suffix for R/W mode. For example, 5d95413513ec:[ro|rw].
Mounts all the defined volumes from the referenced containers. |
Expose | --expose=[ ] | expose | Expose ports without publishing them to the host machine. The ports will only be accessible to linked services. |
Ports | -p=[ ] | ports | Publish a container᾿s port or a range of ports to the host. |
Extra Hosts | --add-host=[ ] | extra_hosts | Specify one or more additional hostname : IP mappings. |
Links | --link=[ ] | links | Link to containers in another service.
Either specify both the service name and the link alias (SERVICE:ALIAS), or just the service name (which will also be used for the alias). |
Networking | --network_mode | network_mode | Specify networking mode. Choose from the same values as the docker client --network_mode parameter (none, bridge, host). |
Capabilities Add | --cap-add=[ ] | cap_add | Specify Linux capabilities to add. |
Capabilities Drop | --cap-drop=[ ] | cap_drop | Specify Linux capabilities to drop. |
Container Name | --name | container_name | Specify a custom container name, rather than a generated default name. |
CPU Shares | --cpu-shares | cpu_shares | Specify CPU shares using integers (relative weight). |
CPU Set | --cpuset-cpus | cpuset | Specify CPUs in which to allow execution (0-3, 0,1). |
Devices | --device=[ ] | devices | Specify a device mapping. |
DNS Search | --dns-search=[ ] | dns_search | Specify the DNS search domain for the container to use. |
Domain Name | No equivalent | domainname | Specify the domain name inside the container. |
Hostname | --hostname | hostname | Specify the hostname to set for the container (not its host). |
Entrypoint | --entrypoint | entrypoint | Specify a comma-delimited list of commands to execute in order. This overrides the Run Command. |
Working Dir | --workdir | working_dir | Specify the base working directory from which any commands passed will be executed. |
User | --user | user | Specify the username or UID to use when running. |
Log Driver | --log-driver | log_driver | Specify a logging driver for the service’s containers (None, JSON file, Syslog, Journald, GELF, Fluentd). |
Log Options | --log-opt=[] | log_opt | Specify logging options for the logging driver. Logging options are key value pairs. |
MAC Address | --mac-address | mac_address | Specify a MAC address. (format:12:34:56:78:9a:bc). |
Memory Limit | --memory | mem_limit | Specify the total virtual memory space for processes inside the container. |
Memory+Swap Limit | --memory-swap | memswap_limit | Specify the total memory + swap space to provide to the container. |
PID | --pid | pid | Set the PID mode to the host PID mode. |
Privileged | --privileged | privileged | Start the container in privileged mode. Be sure to understand the security implications of this. |
Read-Only | --read-only | read_only | Mount the container's root filesystem as read-only. |
STDIN Open | -a stdin | stdin_open | Attach the container to STDIN (Standard Input). |
TTY | -t | tty | Allocate a pseudo-tty. |
Restart | --restart | restart | Specify the container restart policy on exit as one of:
|
Security Options | --security-opt=[ ] | security_opt | Specify alternative security options. |
Managing Application Stacks with Oracle Container Cloud Service
Learn about application stacks, how to create them, and how to manage them.
About Stacks
An Oracle Container Cloud Service application stack (or simply ‘stack’) comprises all of the necessary configuration for running a set of services as Docker containers in a coordinated way and managed as a single entity, plus default deployment directives.
Note that stacks themselves are neither containers nor images running in containers, but rather are high-level configuration objects that you can create, deploy, and manage using Oracle Container Cloud Service.
For example, a stack might be one or more WordPress containers and a MariaDB container. Likewise a cluster of database or application nodes can be built as a stack.
Oracle Container Cloud Service comes with a number of pre-configured stacks. You can use these pre-configured stacks just as they are, or customize them and save them. You can also create new stacks, adding services to the stack as required.
If you subsequently decide you no longer need a stack, you can remove the stack definition from the Oracle Container Cloud Service database. Note that if there’s already a running deployment based on a stack, removing the stack definition doesn’t affect any currently running containers.
Managing Stacks
You manage both stacks you’ve created and pre-configured stacks that come with Oracle Container Cloud Service using the Oracle Container Cloud Service Container Console.
Creating a Stack
You can create a new stack using the Oracle Container Cloud Service Container Console. The new stack will comprise all of the necessary configuration for running a set of services in a coordinated way, managed as a single entity, plus default deployment options.
Description of the illustration occs_new-stack-multi-service-canvas-1.png
Having created the stack, you’re now ready to deploy it (see Deploying a Stack).
Deploying a Stack
When you’ve defined an application stack, you’re ready to deploy it on hosts in a resource pool that you specify.
Defining Dependencies between Services in a Stack using Phases
The services in a stack are often dependent on each other. In some cases, it's important that services start in a specific order. In other cases, you might not want one service to start until a number of other services have started successfully.
-
in the case of a service for which health checks have been defined, the service is considered healthy if all the health checks are passing
-
in the case of a service for which no health checks have been defined, the service is considered healthy if all containers for the service are running
- On the Stacks page of the Container Console, click the Edit button beside the stack name to display the Stack Editor.
- Click Advanced Editor to display the Advanced (YAML) Stack Editor, showing the YAML to deploy the stack.
Description of the illustration occs_stack-phased-services-1.png - For each service for which you want to define a phase:
- Click Done to save your changes and close the Advanced (YAML) Stack Editor.
Managing Docker Containers with Oracle Container Cloud Service
Learn about Docker containers and how to manage them.
About Docker Containers
A Docker container is a process that’s created to run an application held in a Docker image.
The Docker container includes everything the application needs in order to run, including executable code, a runtime environment, system tools, and system libraries. This containerized approach ensures that the application will always run the same, regardless of the environment in which it’s running.
When an operator executes a docker run
command, the container process that runs is isolated in that it has its own file system, its own networking, and its own isolated process tree separate from the host.
Managing Docker Containers
Having deployed a service or stack, you can use the Oracle Container Cloud Service Container Console to manage the Docker containers that are created for the deployment.
You can also manage Docker containers that are not associated with a deployment because they were started directly from a Docker image (see Starting a Docker Container Directly from a Docker Image).
To manage containers using the Oracle Container Cloud Service Container Console:
Accessing an Application Running Inside a Deployed Container
After you’ve deployed a service or stack as one (or more) Docker containers, you’ll want to test and use the applications running inside the deployed containers.
Before you can access the application inside a container, you’ll need to find out the IP address and port number of the host on which the container has been deployed. You can then construct the URLto access the application.
To access an application running inside a deployed container using the Oracle Container Cloud Service Container Console:
- On the Deployments page of the Container Console, click the name of the application that you want to access. The Deployments Details page is displayed.
- Display the Stack YAML tab and note down the host port value specified for the
ports
option. If two values are shown, the host port is the value before the colon. For example, if you seeports: -"9000:80/tcp"
, the host port is 9000. - Display the Containers tab, click the name of the host running the application you want to access, and note down the host’s IP address shown in the public_ip field. For example, 198.51.100.254.
- Assemble a URL from the host’s IP address and the port specified for the deployment that you’ve just noted down. For example, http://198.51.100.254:9000.
- In a browser, navigate to the URL you’ve assembled to access the application running inside the deployed container.
Enabling Docker Containers to Communicate With Each Other
Learn how to enable Docker containers to locate each other so they can communicate and operate together.
About Container Communication
To communicate with each other, Docker containers require DNS information to find out the location of other containers. Oracle Container Cloud Service maintains DNS information for the running containers that it’s managing in its Service Discovery database.
A service running in one Docker container might have a dependency on a second service running in another container on the same host or on a different host. Similarly, multiple containers might be running the same service on the same or different hosts for load balancing and high-availability reasons. In these situations, containers use DNS information to communicate with each other.
When a new container starts, Oracle Container Cloud Service automatically registers the new container’s IP address and port number in the Service Discovery database. In some situations, you might want to manually enter or update DNS information in the Service Discovery database (for example, to initially bootstrap a container).
The record for each container in the Service Discovery database comprises:
-
a key, made up of a unique id generated for the deployed container, concatenated with the id and name of the deployed service
-
a value, made up of the IP address of the host running the container, concatenated with the port exposed by the service
To enable a running container to become aware of a newly started container on which it depends, you’ll need to include functionality in your stack to act as a listener to poll the Service Discovery database for container keys that contain the name of the dependency. That code can then write the DNS information for matching containers, which can in turn be regularly queried by other running containers to obtain the latest information about dependent containers. Some of the Oracle Container Cloud Service example stacks include this functionality. To find out more, see the information about building the example stacks on GitHub.
Managing Entries in the Service Discovery Database to Enable Container Communication
You can view the DNS information recorded for running Docker containers in the Oracle Container Cloud Service Service Discovery database. This information enables containers to communicate with each other.
Viewing the Log Files of a Running Container
You can view the log files of a running container using the Oracle Container Cloud Service Container Console.
For example, you might want to view the log files of a particular container on a specific host to diagnose issues.
To view the log files of a running container using the Oracle Container Cloud Service Container Console:
Managing Docker Images with Oracle Container Cloud Service
Learn about Docker images and how to manage them.
About Docker Images
A Docker image holds the application that you want Docker to run, along with any dependencies. A Docker image is stored in a Docker registry.
When a service is deployed (either singly, or as part of a stack) for the first time, the Docker image for the service is pulled from the specified Docker registry (either the public Docker registry or a private Docker registry) and added to the list of images managed by Oracle Container Cloud Service. The same Docker image can appear multiple times in the list of images managed by Oracle Container Cloud Service if:
-
a service based on the image is deployed on multiple hosts
-
the image has multiple tags associated with it
Once an image has been pulled from a Docker registry onto a host managed by Oracle Container Cloud Service, you can also start a container directly from the image (rather than starting a container by deploying a service). When you run the image in this way, you specify options for the container and manage the container directly using the Oracle Container Cloud Service Container Console. Note that in this case, Oracle Container Cloud Service doesn’t create a deployment object for the running container. See Starting a Docker Container Directly from a Docker Image.
Managing Docker Images
Having deployed a service or stack, you can use the Oracle Container Cloud Service Container Console to manage the Docker images that have been pulled from public or private Docker registries.
To manage images using the Oracle Container Cloud Service Container Console:
Starting a Docker Container Directly from a Docker Image
You don’t have to deploy a service or stack to start a Docker container based on a Docker image. You can start a Docker container directly from an image that has already been pulled onto a host managed by Oracle Container Cloud Service.
For example, you might want to quickly start a simple container without specifying orchestration details.
Note that if you start a container directly from an image rather than by deploying a service or stack, Oracle Container Cloud Service enables you to manage the container directly, and doesn’t create a deployment object.
To start a Docker container directly from a Docker image using the Oracle Container Cloud Service Container Console:
Pushing a Docker Image to a Docker Repository
When you want to store a new or updated image in a Docker repository, you can use the Oracle Container Cloud Service Container Console to add a tag to the image and then push it to the repository.
For example, you might have pulled the latest version of an application from Docker Hub, updated the local version and stored it in your local Docker repository as a new image, and then used the Container Console to deploy the image as a service to test it. If the image passes the tests, you’ll want to push the new version to Docker Hub to replace the previous version by giving it the ‘latest’ tag.
You can use tags to push an image to any repository in any registry, not just to the registry it was originally pulled from. Note that a definition of the registry containing the repository to which you want to push the image must already exist in Oracle Container Cloud Service. Also note that the user specified in the registry definition must have sufficient privileges to write to the registry (see Creating a Docker Registry Definition).
You can use the same tag for multiple images. For example, you might want to push several different images to different repositories, but add the same ‘latest’ tag to each of them.
You can assign multiple tags to the same image. For example, you might add both a version number tag and the ‘latest’ tag to the same image.
A typical scenario might be:
-
The helloworld image is stored in the helloworld repository in the jsmith Docker registry. The most recent production version is version 5, and has the tags ‘v5’ and ‘latest’ in the repository.
-
You’ve already created a service in the Container Console based on version 5 of the helloworld image, and deployed it. When you defined the service, you specified jsmith/helloworld:latest as the image to use.
-
A developer pushes a new version of the helloworld image to the repository with the tag ‘v6’, which you want to test to assess whether it’s production quality.
-
You create a new service in the Container Console and specify jsmith/helloworld:v6 as the image to use. You deploy the service and test it.
-
The image passes all the tests, so you decide to make version 6 the new production version.
-
You add the ‘latest’ tag to the version 6 image in the Container Console and push the image to the jsmith/helloworld repository. The image that was previously tagged ‘latest’ is overwritten.
To push a Docker image to a Docker repository using the Oracle Container Cloud Service Container Console:
Managing Deployments with Oracle Container Cloud Service
Learn about deployments and how to manage them.
About Deployments
An Oracle Container Cloud Service deployment comprises a service or stack in which Docker containers are managed, deployed, and scaled according to a set of orchestration rules that you’ve defined. Every time you deploy a service or a stack, Oracle Container Cloud Service creates a deployment. A single deployment can result in the creation of one or many Docker containers, across one or many hosts in a resource pool. And if you deploy the same service (or stack) multiple times, Oracle Container Cloud Service creates a corresponding number of deployments.
The orchestration functionality delivered by Oracle Container Cloud Service begins when you deploy a service and stack. The deployment of a service or stack generates a ‘deployment object’, or simply a ‘deployment’. Docker images are pulled, Docker containers are created, and communication paths between services are set up. The orchestration rules specify how many containers to run per pool, per host, or per tag, and how to select the hosts on which to run the containers. You save default orchestration policies with service and stack definitions, but you can override the default policies for specific deployments.
Each deployment is unique, and has its own lifecycle. A deployment is created when you click Deploy. If you subsequently stop a deployment, any containers created for the deployment are stopped and removed. If you restart a stopped deployment, it keeps the same deployment ID but new containers are created for it.
Managing Deployments
Having deployed a service or stack, you can use the Oracle Container Cloud Service Container Console to manage the deployment.
Scaling a Running Deployment with Oracle Container Cloud Service
When you deploy a service or stack, you specify how many Docker containers the deployment is to start. After it’s been deployed, you can use the Oracle Container Cloud Service Container Console to increase (scale out) or decrease (scale in) the number of containers the running deployment uses.
Monitoring the Health of a Deployment
Having deployed a service or stack, you can use the Oracle Container Cloud Service Container Console to monitor the status of that particular deployment so that you can take action to address any issues that arise.
To monitor the health of a deployment using the Oracle Container Cloud Service Container Console:
- To see the status of deployed services and stacks:
- To see the status of containers in a deployed service or stack:
- Go to the Containers page of the Container Console to see a summary of the status of each Docker container.
- Click the name of a Docker container to see detailed information about the container, including its current status, how long it has been running, and information it has output to log files.
- To see even more detailed information about the status of each deployment:
- Go to the Tasks & Events page of the Container Console.
- Click one of Event Log, Status Updates, or Tasks according to the type of information you want to see.
- Select the information severity levels to display.
- Enter an appropriate search string so that you only see information about the services and stacks you’re interested in.
Stopping and Re-starting Service and Stack Deployments
Periodically, you’ll want to stop and restart service and stack deployments that you’ve previously started.
For example, you might want to deploy a more recent version of a service on the same host as an existing version. If you don’t need access to deployed containers running the existing version, you can stop the existing deployment to release CPU and memory for containers running the new version. Having stopped the deployment, you can remove the deployment. Or you might decide to keep the deployment, just in case you want to restart and use it again later.
Stopping a Service or Stack Deployment
Stop a deployment of a service or stack when you no longer require its containers to be running, perhaps because you want to temporarily (or permanently) free up resource on a host.
To stop a currently running service or stack deployment using the Oracle Container Cloud Service Container Console:
Re-starting a Service or Stack Deployment
Re-start the deployment of a service or stack that’s previously been stopped, perhaps to resume using an earlier version.
To restart a service or stack deployment using the Oracle Container Cloud Service Container Console:
Managing Docker Registries with Oracle Container Cloud Service
Learn about registries and how to manage them.
About Docker Registries and Registry Definitions
A Docker registry is a system for storing and sharing tagged versions of Docker images. A Docker registry is organized into named repositories. Each Docker repository is associated with a particular version of one or more images.
Before Oracle Container Cloud Service can deploy a service based on a Docker image, it must already know the location of the Docker registry from which to pull the image. A registry definition containing location information must exist for each Docker registry from which Oracle Container Cloud Service will pull images. Similarly, if you’re going to use Oracle Container Cloud Service to push images to a Docker registry, an appropriate registry definition must exist.
Oracle Container Cloud Service comes with a definition for the public Docker Hub registry out-of-the-box, so you can get started with public images right away. But you’ll have to create a registry definition for any other public or private registry from which you want Oracle Container Cloud Service to pull images, or to which you want it to push images.
Managing Docker Registry Definitions
You manage definitions of public or private Docker registries that you want Oracle Container Cloud Service to pull images from or push images to, using the Oracle Container Cloud Service Container Console.
Creating a Docker Registry Definition
A registry definition must exist for each Docker registry that you want Oracle Container Cloud Service to pull images from or push images to.
Managing Tags with Oracle Container Cloud Service
Learn about tags, how to use them to manage your Docker environment, how to create them, and how to manage them.
About Tags
Oracle Container Cloud Service tags are a way to categorize and organize resource pools and the hosts within them, enabling you to manage your Docker environment more effectively.
When defining orchestration policies, tags give you fine-grained control over which hosts in a resource pool to deploy a service or stack on.
Having created a new tag, you can use it:
-
for resource pools
-
for hosts, to collectively identify multiple hosts on which a service can be deployed
-
for services in the Service Editor, when specifying the hosts on which a service is to run using the per-tag (across hosts in this pool with tag of... availability option.
-
for deployments, to override a service’s default orchestration details and specify the hosts on which the service is to run
You can also use tags as search criteria when looking for particular hosts across your entire managed Docker environment.
Note that the tags you use to organize resource pools and hosts are totally unrelated to the tags you use when pushing Docker images to a repository (see Pushing a Docker Image to a Docker Repository).
Creating and Assigning Tags
You can create and assign tags using the Oracle Container Cloud Service Container Console.
Tags are a useful way to identify Oracle Container Cloud Service objects with common characteristics, or that you want to use in a similar way.
Creating New Tags Using the Tags Page
You can create new tags in advance of assigning them using the Tags page of the Oracle Container Cloud Service Container Console.
-
you want to enter several tags in advance
-
you want everyone on the team to use the same set of tags
-
you want the tags to adhere to particular naming conventions
To create new tags using the Tags page of the Oracle Container Cloud Service Container Console:
Creating and Assigning New Tags When Defining Hosts and Resource Pools
You can create new tags when defining hosts and resource pools.
-
you’re defining tags for your own use
-
you’re familiar with your team’s tag naming standards
To create new tags when defining hosts and resource pools using the Oracle Container Cloud Service Container Console:
Managing Tags Using the Tags Page
You can manage tags using the Tags page of the Oracle Container Cloud Service Container Console.
-
you want to see the resource pools and hosts to which a specific tag is assigned
-
you want to remove a tag from the system
-
you want to assign a tag to (or remove a tag from) multiple hosts and resource pools
To manage tags using the Tags page using the Oracle Container Cloud Service Container Console:
Monitoring Tasks, Events, and Status Updates with Oracle Container Cloud Service
Learn about tasks, events, status updates, and how to monitor them.
About Tasks, Events, and Status Updates
Tasks, events, and status updates enable you to monitor the Docker environment managed by Oracle Container Cloud Service.
-
add a deployment
-
pull a Docker image from a registry
-
confirm that the docker image has been pulled
-
create a docker image on host
-
start the docker image
Status updates report the progress of particular recurring events and tasks (for example, starting a deployment, or running a health check). Status updates have a lifecycle, meaning their severity and description can change. For example, a container creation event might initially fail and generate a status update with a severity of Error. However, if the same container creation event is re-run successfully, the severity of the existing status update is downgraded to Cleared and its description changes. Note that not all events generate status updates.
Tasks are cancelable actions created by Oracle Container Cloud Service in response to your requests. Tasks are long-running, and can involve multiple events and objects. For example, if you stop several containers, Oracle Container Cloud Service creates a task to carry out the action on your behalf because it could take some time for multiple events on each of the containers to complete. All tasks generate status updates, and can be canceled while they are still running.
Oracle Container Cloud Service classifies events and status updates with a set of severity levels.
Managing Profile Settings with Oracle Container Cloud Service
Learn about when and how to change and view profile settings.
Changing and Viewing Profile Settings
Find out how to change the username and password with which you sign into Oracle Container Cloud Service Container Console, and how to see the value of the API token that uniquely identifies your username.
Using Template Functions and Arguments with Oracle Container Cloud Service
Learn about incorporating template functions and arguments in stack and service definitions.
About Template Functions and Arguments
Template functions enable you to programmatically access and update details about service and stack deployments managed by Oracle Container Cloud Service. Template arguments expose a deployment’s properties so that you can manipulate them using template functions.
You can incorporate Oracle Container Cloud Service template functions and arguments into service and stack definitions using the Container Console’s Service Editor and Advanced (YAML) Stack Editor to programmatically get and set values for configuration options and environment variables.
Typically, template functions and arguments return values from:
-
the Key/Value store in Oracle Container Cloud Service’s Service Discovery database
-
Oracle Container Cloud Service environment variables (with names starting ‘OCCS_’) related to the deployment
One way to use template functions and arguments is to call them to set environment variables in a running container's host. Application code in the container can then use those environment variables.
You’ll also find template functions and arguments particularly useful when you want to create generic services and stacks that can be reused to meet different requirements. For example, you might want to define a stack to deploy a blogging application that comprises WordPress and a mariadb database. If you only have one such blogging application to deploy, you can create a stack definition that explicitly specifies the Docker images to run as Docker containers for the application, the host ports to use when the application is deployed, and the database root password.
Such a stack definition is shown below:
# https://hub.docker.com/_/wordpress/
# Example docker-compose.yml for wordpress:
# Run docker-compose up, wait for it to initialize completely,
# and visit http://localhost:8080 or http://host-ip:8080.
wordpress:
image: wordpress:latest
ports:
- 8080:80
links:
- db:mysql
db:
container_name: db
image: mariadb:latest
environment:
- MYSQL_ROOT_PASSWORD=Eric-Password
So far, so good. But if you have ten similar blogging applications to deploy, creating and maintaining a separate stack definition for each application could quickly become tiresome.
By incorporating template functions in a stack definition, you can reuse the same stack definition to deploy multiple different applications. In the case of deploying the ten different blogging applications, you could incorporate template functions into a single stack definition to interrogate the Key/Value store in the Oracle Container Cloud Service Service Discovery database and return the port and the database root password to use for each blogging application, as well as the name and location of each application’s data partition mount point.
Such a stack definition is shown below:
# https://hub.docker.com/_/worddivss/
# Example docker-compose.yml for wordpress:
# Run docker-compose up, wait for it to initialize completely,
# and visit http://localhost:8080 or http://host-ip:8080.
wordpress:
image: wordpress:latest
ports:
- {{kv_get .EnvironmentID .StackID .ServiceID "port"}}:80
links:
- db:mysql
db: # ensure db sorts before wordpress
container_name: db
image: mariadb:latest
environment:
- MYSQL_ROOT_PASSWORD={{kv_get {{.ServiceID}} "pass" }}
volumes:
- /NFS/{{.EnvironmentID}}/{{.DeploymentID}}/{{.ServiceID}}/{{.ServiceSlot}}:/mnt/data
Adding Template Functions and Arguments to Service Definitions
You can add template functions to a service definition, and pass in template arguments, enabling you to programmatically access and update details about the service when it’s deployed.
Adding Template Functions and Arguments to Stack Definitions
You can add template functions to a stack definition, and pass in template arguments, enabling you to programmatically access and update details about the stack when it’s deployed.
Template Function and Argument Reference
When including template functions and arguments you can include in service and stack definitions using the Oracle Container Cloud Service’s Service Editor and Advanced (YAML) Stack Editor, you must use the correct syntax.
For template functions and arguments to be evaluated by Docker Compose, you must insert them into the YAML beneath the correct service level keys:
-
If you’re editing the YAML indirectly using the Service Editor’s Builder tab or Docker Run tab, provided you’ve used the template functions and arguments appropriately to set configuration options, they are automatically included in the YAML in the correct location.
-
If you’re editing the YAML directly using the Service Editor’s YAML tab or the Advanced (YAML) Stack Editor, you manually insert the template functions and arguments beneath the following service level keys:
-
command
-
environment
-
hostname
-
labels
-
network_mode
-
ports
-
volumes
-
volumes_from
-
Template Functions
Use the following template functions when defining services in the Oracle Container Cloud Service’s Service Editor and Advanced (YAML) Stack Editor. Note that template function calls must always be enclosed within double curly braces as {{function-name}}
, and that function names must always be capitalized exactly as shown below.
Template Function and parameters | Description | Example Value of Environment Variable in Deployment | Example Function Call with Arguments | Example Evaluation |
---|---|---|---|---|
api_token | Extracts the token of the deployment creator. | (not applicable) | USER_API_TOKEN={{api_token}} | USER_API_TOKEN=36bf51e24218d492 |
expand "separator" "string" min qty | Ranges over an index from a given minimum value up to the number specified by qty minus 1, and appends that value to a string separated by a separator. | (not applicable) | MY_ZKS={{expand "," "zk-" 0 3}} | MY_ZKS=zk-0,zk-1,zk-2 |
hostip_for_interface host-interfaces-and-ip-addresses "interface-to-match" | Extracts the IP address for an interface of the host running the container. | OCCS_HOSTIPS=eth0: 172.16.44.183, eth1: 10.9.1.2, docker0: 172.17.42.1 | MY_ETH1_IP2={{hostip_for_interface .HostIPs "eth1"}} | MY_ETH1_IP2=10.9.1.2 |
hostip_with_prefix host-interfaces-and-ip-addresses "prefix-to-match" | Extracts the IP address that matches the prefix of the host running the container. | OCCS_HOSTIPS=eth0: 172.16.44.183, eth1: 10.9.1.2, docker0: 172.17.42.1 | MY_172_16_IP={{hostip_with_prefix .HostIPs "172.16."}} | MY_172_16_IP=172.16.44.183 |
hostips_keys host-interfaces-and-ip-addresses | Lists the interfaces of the host running the container. | OCCS_HOSTIPS=eth0: 172.16.44.183, eth1: 10.9.1.2, docker0: 172.17.42.1 | MY_INTERFACES={{hostips_keys .HostIPs}} | MY_INTERFACES=eth0 eth1 docker0 |
hostips_values host-interfaces-and-ip-addresses | Lists the IP addresses of the host running the container. | OCCS_HOSTIPS=eth0: 172.16.44.183, eth1: 10.9.1.2, docker0: 172.17.42.1 | MY_IPS={{hostips_values .HostIPs}} | MY_IPS=172.16.44.183 10.9.1.2 172.17.42.1 |
kv_get "arg-1" "arg-2" "arg-n" | Accepts any number of arguments, joins them together using a “/” separator, then uses the generated key to look up a value in the Key/Value store. If a value is not found, the lookup results in an error and templating fails. | (not applicable) | MY_TEST={{kv_get "arbitrarily" "defined" "key" "path"}} | MY_TEST=172.16.44.183 |
kv_path "arg-1" "arg-2" "arg-n" | Accepts any number of arguments and joins them together using a “/” separator as the evaluated result.
kv_get calls kv_path to generate the path key. |
(not applicable) | MY_TEST_PATH={{kv_path "arbitrarily" "defined" "key" "path"}} | MY_TEST_PATH=arbitrarily/defined/key/path |
map_get "key-value-pairs-string" "record-separator" "key-value-separator" "key" | Lists the value of a particular key in a specified string of key/value pairs, given a list of key/value pairs, a record separator, and a key/value separator. | OCCS_HOSTIPS=eth0: 172.16.44.183, eth1: 10.9.1.2, docker0: 172.17.42.1 | MY_ETH1_IP2={{map_get .HostIPs "," ":" "eth1"}} | MY_ETH1_IP2=10.9.1.2 |
map_keys "key-value-pairs-string" "record-separator" "key-value-separator" | Lists all the keys in a specified string of key/value pairs, given a record separator, and key/value separator. | OCCS_HOSTIPS=eth0: 172.16.44.183, eth1: 10.9.1.2, docker0: 172.17.42.1 | MY_ETH1_IP2={{map_keys .HostIPs "," ":"}} | MY_ETH1_IP2=eth0 eth1 docker0 |
map_values "key-value-pairs-string" "record-separator" "key-value-separator" | Lists all the values in a specified string of key/value pairs, given a record separator, and key/value separator. | OCCS_HOSTIPS=eth0: 172.16.44.183, eth1: 10.9.1.2, docker0: 172.17.42.1 | MY_IPS={{map_values .HostIPs "," ":"}} | MY_IPS=172.16.44.183 10.9.1.2 172.17.42.1 |
plus number-1 number-2 | Adds a value with another value. | (not applicable) | MY_1542={{plus 1500 42}} | MY_1542=1542 |
plus_ip ip-address number | Adds a number to an IP address. | OCCS_SERVICE_SLOT=2 | MY_OTHERIP={{plus_ip "10.1.0.100" .ServiceSlot}} | MY_OTHERIP=10.1.0.102 |
plus_suffix "separator" "string" number | Extracts the suffix of a given string (up to an occurrence of the specified separator character), adds the specified number to the extracted suffix, and returns the string with the updated suffix. | OCCS_SERVICE_SLOT=2 | MY_OTHERIP={{plus_suffix "." "10.1.0.100" .ServiceSlot}} | MY_OTHERIP=10.1.0.102 |
proxy "service-id:port" | A multi-host directive that routes the endpoint of given SERVICE_ID:PORT
The proxy directive creates a TCP proxy that the container uses to reach a remote service endpoint. When the container makes a connection to the endpoint, the proxy looks up the given service in the Service Discovery database. If the proxy finds matching services, it chooses one at random and proxies the incoming connection to it. If the proxy finds no matching services, it closes the incoming connection and an error is logged. |
WORDPRESS_DB_HOST={{ proxy "SERVICE_ID:PORT" }} | WORDPRESS_DB_HOST={{ proxy "db:3306" }} | WORDPRESS_DB_HOST=172.17.42.1:20009 |
sd_deployment_containers_path "sibling-service" port | Generates the Service Discovery container path given a sibling service and port. | OCCS_DEPLOYMENT_ID=NGINX-load-balanced-with-HAProxy | MY_BACKEND_KEY={{sd_deployment_containers_path "nginx-backend-eg" 80}} | MY_BACKEND_KEY=apps/nginx-backend-eg-NGINX-load-balanced-with-HAProxy-80/containers |
Template Arguments
Use the following arguments when defining services in the Oracle Container Cloud Service’s Service Editor and Advanced (YAML) Stack Editor.
The examples below assume you’ve defined a stack with the ID “user-blogs” to deploy a blogging application named “Eric’s Blog”. The “user-blogs” stack comprises a WordPress service and a mariadb service.
Note that argument names must always be preceded by a period and capitalized exactly as shown.
Template Argument | Description | Example Use to set MY_ENV_VAR | Example Evaluation |
---|---|---|---|
.ContainerHostname | The hostname used within the container. | MY_ENV_VAR={{.ContainerHostname}} | MY_ENV_VAR=2.wordpress.erics-blog |
.ContainerName | The name of the container. | MY_ENV_VAR={{.ContainerName}} | MY_ENV_VAR=2.wordpress.erics-blog |
.CreatedBy | The username who created the deployment. | MY_ENV_VAR={{.CreatedBy}} | MY_ENV_VAR=“admin” |
.DeploymentID | The deployment ID for a deployment. | MY_ENV_VAR={{.DeploymentID}} | MY_ENV_VAR=“erics-blog” |
.DeploymentName | The deployment name for a deployment. | MY_ENV_VAR={{.DeploymentName}} | MY_ENV_VAR=“Eric's Blog” |
.EnvironmentID | The optional environment for a deployment. If not specified for a deployment, “default” is used. | MY_ENV_VAR={{.EnvironmentID}} | MY_ENV_VAR=“default” |
.HostID | The GUID of the host running the container. | MY_ENV_VAR={{.HostID}} | MY_ENV_VAR=172.16.44.183 |
.HostIPs | A map of interface to IP addresses for the host. | MY_ENV_VAR={{.HostIPs}} | MY_ENV_VAR=eth0: 172.16.44.183, eth1: 10.9.1.2, docker0: 172.17.42.1 |
.Hostname | The hostname of the host running the container. | MY_ENV_VAR={{.Hostname}} | MY_ENV_VAR=somehost.example.com |
.KVDeploymentPath | A shortcut for joining the environment and the deployment ID. | MY_ENV_VAR={{.KVDeploymentPath}} | MY_ENV_VAR=production/erics-blog |
.KVServicePath | A shortcut for joining the environment, deployment ID, and service ID. | MY_ENV_VAR={{.KVServicePath}} | MY_ENV_VAR=production/erics-blog/wordpress |
.KVServiceSlotPath | A shortcut for joining the environment, deployment ID, service ID, and service slot. | MY_ENV_VAR={{.KVServiceSlotPath}} | MY_ENV_VAR=production/erics-blog/wordpress/2 |
.ServiceID | The ID of the service used to create the container. | MY_ENV_VAR={{.ServiceID}} | MY_ENV_VAR=wordpress |
.ServiceIDs | The service IDs of the deployment used to create the containers. | MY_ENV_VAR={{.ServiceIDs}} | MY_ENV_VAR=db wordpress |
.ServiceSlot | The integer slot of the container from 0 to quantity-1 of the service.
If three containers were specified for the WordPress deployment for roberts-blog, .ServiceSlot would be 0 for the first container, 1 for the second, and 2 for the third. |
MY_ENV_VAR={{.ServiceSlot}} | MY_ENV_VAR=0 |
.ServiceSlotStr | The slot in string format. | MY_ENV_VAR={{.ServiceSlotStr}} | MY_ENV_VAR=0 |
.StackID | The ID of the stack used to define the deployment. | MY_ENV_VAR={{.StackID}} | MY_ENV_VAR=“user-blogs“ |
Using the Oracle Container Cloud Service REST API
Learn about the Oracle Container Cloud Service REST API and how to use it to manage your Docker environment.
About the Oracle Container Cloud Service REST API
You can use the Oracle Container Cloud Service REST API to incorporate Oracle Container Cloud Service functionality into your web applications.
The Oracle Container Cloud Service REST API exposes Oracle Container Cloud Service functionality as HTTP methods to enable you to incorporate the functionality using Representational State Transfer (REST) requests and responses. REST offers a simple, light-weight API for applications that don’t require the server to maintain state information or message exchange. See Calling the Oracle Container Cloud Service REST API.
If you want to hold information in persistent storage, you can save keys and values in the Oracle Container Cloud Service Key/Value Store database for retrieval by calls to the Oracle Container Cloud Service REST API. See Adding Keys and Values to the Key/Value Store Database and Example REST API Calls to Access the Key/Value Store Database.
Some Oracle Container Cloud Service REST API methods (usually those performing PUT, POST, and DELETE operations) require authentication details in order to run, in the form of an API token. The API token uniquely identifies the SSO user associated with it. You can see and copy the API token associated with your SSO username on the My Profile page (see Changing and Viewing Profile Settings). Typically, you'll include the API token as the value of the Bearer token in the authorization header of a script calling a method that requires authentication. Note that a new API token value is generated if you change the value in the Username field on the My Profile page, so you’ll have to update any scripts that included the old API token.
Calling the Oracle Container Cloud Service REST API
As a developer, you can use the functionality provided by the Oracle Container Cloud Service REST API to incorporate Oracle Container Cloud Service functionality into your web applications using Representational State Transfer (REST) requests and responses. REST offers a simple, light-weight API for applications that don’t require the server to maintain state information or message exchange.
For more information, see REST API for Oracle Container Cloud Service.
Adding Keys and Values to the Key/Value Store Database
You can store values for keys in the Key/Value Store database using the Oracle Container Cloud Service Container Console for subsequent retrieval by calls to the Oracle Container Cloud Service REST API.
Example REST API Calls to Access the Key/Value Store Database
You can access the Key/Value Store database using the Oracle Container Cloud Service REST API.
-
to insert a value in the Key/Value Store database using the REST API:
curl -si -X "PUT" -H "Authorization: Bearer 394ed660d52ac8d8" "http://apitest.occs.example.oraclecloud.com:80/api/kv/dummykey" -d 'dummy value'
-
to get a value from the Key/Value Store database using the REST API:
curl -si -X "GET" -H "Authorization: Bearer 394ed660d52ac8d8" "http://apitest.occs.example.oraclecloud.com:80/api/kv/dummykey"
which might generate the response:[{"Key":"dummykey","Value":"ZHVtbXkgdmFsdWU="}]
-
to delete a value from the Key/Value Store database using the REST API:
curl -si -X "DELETE" -H "Authorization: Bearer 394ed660d52ac8d8" "http://apitest.occs.example.oraclecloud.com:80/api/kv/dummykey"
As well as using the Oracle Container Cloud Service REST API, you can also add, edit, and remove values in the Key/Value Store database using the Oracle Container Cloud Service Container Console (see Adding Keys and Values to the Key/Value Store Database).