Description
The IBM Containers plug-in uses the Cloud Foundry IBM® Containers command-line utility (cf ic) to interact with containers running in IBM Bluemix®.
- Overview
- Documentation
- Version history
Quick Info
Product
HCL DevOps Deploy (HCL Launch)
Type
Plug-in
Compatibility
HCL Launch version 7.3.2.8 and later, HCL Deploy version 8.0.1.3 and later
Created by
HCLSoftware
Website
Published Date
Last Updated
Summary
Usage
Steps
Summary
Available Steps
- Install IBM Containers Plugin - Install the IBM containers plugin to run native docker commands from within the Cloud Foundry CLI
- Uninstall IBM Containers Plugin - Uninstall the IBM containers plugin.
- Login to Cloud Foundry - Login to the Cloud Foundry instance in order to use the CF Containers CLI.
- Logout of Cloud Foundry - Logout of the Cloud Foundry instance.
- Set Namespace - Set the namespace for the targeted organization.
- Initialize Plugin - Refresh the bearer token for authentication and reinitialize the CLI. Will also set the output properties ‘cfic.dockerHost’ and ‘cfic.dockerCertPath’. Use these to set the ‘–host’ and ‘–tlscert’ with the docker CLI. This will allow use of the Docker CLI directly for the current session to run supported Docker commands.
- Build Image from Dockerfile - Build a Docker image locally or in the private Bluemix repository using a Dockerfile.
- Run Container - Start a new container from an image name or id.
- Request IP Address - Request a new floating IP address that can be used within your container cloud service instance.
- Release IP Address - Release an IP address from the container cloud service instance.
- Bind IP Address - Bind a floating IP address to a running container.
- Unbind IP Address - Unbind the IP address allocated to the specified container.
- Execute Command on Container - Execute a command on a running container.
- Start Containers - Start stopped containers.
- Stop Containers - Stop running containers.
- Create Group - Create a container group for scaling containers.
- Remove Group - Remove a container group from the Bluemix repository.
- Update Group - Update specific option for a container group. You may only update one parameter at a time.
Installation
The Cloud Foundry command-line utility must be installed on the agent computer. Install the Cloud Foundry command-line utility from the GitHub repository. No other special steps are required for installing the plug-in in IBM DevOps Deploy. See Installing plug-ins in HCL Deploy for installing and removing plug-ins.
History
| Version | Description |
|---|---|
| 6 | Fixied CVE:CVE-2019-4233 |
| 5 | Added login failure error message from "cf ic login..." command to help users resolve the issue. Previously, the error from the failed login attempt was ignored. |
| 4 | "Unbind IP Address" step now calls the correct groovy script. Support property file encryption. |
| 3 | Added ability to autodiscover Bluemix Registries |
| 2 | Added create group, remove group, and update group steps Improved error logging for acquiring command output |
| 1 | Initial Cloud Foundry Containers integration |
Usage
To use the steps in the plug-in, you must first install and initialize the plug-in. To install and initialize the plug-in, complete the following steps in the process editor:
- Add the Install IBM Containers Plug-in step to the process. Ensure that the Cloud Foundry CLI Path field is set to the directory that contains the Cloud Foundry command-line utility.
- Add the Login to Cloud Foundry step to the process. Again, ensure that the Cloud Foundry CLI Path field is set to the directory that contains the Cloud Foundry command-line utility. Also, specify the Cloud Foundry user name, password, and API endpoint. Optionally, specify the Cloud Foundry organization and space.
- Add the Initialize Plug-in step to the process. This step initializes the command-line interface to use the plug-in that is installed by the Install IBM Containers Plug-in step.
- After these steps have run, the plug-in is installed and initialized. You can now run the following plug-in steps: Build Image from Dockerfile, Run Container, Start Containers, Stop Containers, Set Namespace, Request IP Address, Release IP Address, Bind IP Address, Unbind IP Address, Execute Command On Container, Create Group, Remove Group, and Update Group.
- The following screen capture shows an example process that installs and initializes the plug-in, and then runs a container.
Steps
IBM Containers - Process Steps
- Bind IP Address
- Build Image from Dockerfile
- Create Group
- Execute Command On Container
- Initialize Plug-in
- Install IBM Containers Plug-in
- Log in to Cloud Foundry
- Log out of Cloud Foundry
- Release IP Address
- Remove Group
- Request IP Address
- Run Container
- Set Namespace
- Start Containers
- Stop Containers
- Unbind IP Address
- Uninstall IBM Containers Plug-in
- Update Group
Bind IP Address
Bind a floating IP address to a running container. You must be logged in to Cloud Foundry before running this step by either running the Log in to Cloud Foundry step or by manually logging in on the agent computer.
| Name | Type | Description | Required |
|---|---|---|---|
| Cloud Foundry CLI Path | String | Absolute path to the Cloud Foundry CLI executable file, specified if it is not already on the system path. | No |
| Container Name/ID | String | The name or ID of the container to bind to the IP address. | Yes |
| IP Address | String | The floating IP address to release from the container cloud service. | Yes |
Build Image from Dockerfile
Build a Docker image locally or in the private Bluemix repository by using a Dockerfile text document. You must be logged in to Cloud Foundry before running this step by either running the Log in to Cloud Foundry step or by manually logging in on the agent computer.
| Name | Type | Description | Required |
|---|---|---|---|
| Additional Arguments | String | Additional command-line arguments to pass when running this command (for example, pull). | No |
| Cloud Foundry CLI Path | String | Absolute path to the Cloud Foundry CLI executable file, specified if it is not already on the system path. | No |
| Dockerfile Path | String | The path to the directory that contains the Dockerfile document used to build the image.Artifacts used in the build must also exist in this directory. | Yes |
| Tag | String | The repository name to apply to the created image. | Yes |
Create Group
Create a container group for scaling containers.
| Name | Type | Description | Required |
|---|---|---|---|
| Additional Arguments | String | Any additional argument flags to include with the command, split by a new line. | No |
| Cloud Foundry CLI Path | String | Absolute path to the Cloud Foundry CLI executable file, specified if it is not already on the system path. | No |
| Desired Instances | String | The number of required container instances. This is the number of containers by default. | No |
| Domain Name | String | Domain name to combine with the host name to form the full public route URL (for example, .mybluemix.net). | No |
| Environment Variables | String | Specify a key value pair for each environment variable to set on the containers. Split multiple variables by using a new line (for example, CSS_BIND_APP=MyApplication). | No |
| Exposed Port | String | Expose this port for HTTP traffic on the containers. You cannot include multiple ports for container groups. | No |
| Group Name | String | Name to assign to the group. Must start with a letter and can include uppercase letters, lowercase letters, numbers, periods, underscores, or hyphens. | Yes |
| Host Name | String | Host name to combine with the domain to form the full public route URL. | No |
| Image Name | String | The image to include in each container instance in the container group. You can include commands after the container name (for example, registry.ng.bluemix.net/myimage ping localhost). | Yes |
| Maximum Instances | String | The maximum number of container instances. | No |
| Minimum Instances | String | The minimum number of container instances. | No |
Execute Command On Container
Execute a command on a running container. You must be logged in to Cloud Foundry before running this step by either running the Log in to Cloud Foundry step or by manually logging in on the agent computer.
| Name | Type | Description | Required |
|---|---|---|---|
| Additional Arguments | String | Additional command-line arguments to pass when running this command separated by new lines (for example, user USERNAME). | No |
| Cloud Foundry CLI Path | String | Absolute path to the Cloud Foundry CLI executable file, specified if it is not already on the system path. | No |
| Command | String | The command to run within the container (for example, cp /root/dependency.jar ${JAVA\_HOME}/lib). | No |
| Container Name/ID | String | The name or ID of the container on which to run a command. | No |
Initialize Plug-in
Refresh the bearer token for authentication and reinitialize the CLI. This step will also set the output properties cfic.dockerHost and cfic.dockerCertPath. Use these properties to set the host and tlscert with the Docker CLI. This will allow use of the Docker CLI directly for the current session to run supported Docker commands. You must be logged in to Cloud Foundry before running this step by either running the Log in to Cloud Foundry step or by manually logging in on the agent computer.
| Name | Type | Description | Required |
|---|---|---|---|
| Cloud Foundry CLI Path | String | Absolute path to the Cloud Foundry CLI executable file, specified if it is not already on the system path. | No |
Install IBM Containers Plug-in
Install the IBM Containers plug-in to run Docker commands from within the Cloud Foundry CLI.
| Name | Type | Description | Required |
|---|---|---|---|
| Cloud Foundry CLI Path | String | Absolute path to the Cloud Foundry CLI executable file, specified if it is not already on the system path. | No |
| Path To IBM Containers Plugin | String | Override the default URL with a local path to the IBM Containers plug-in or a URL path. | No |
Log in to Cloud Foundry
Log in to the Cloud Foundry instance in order to use the CF Containers CLI.
| Name | Type | Description | Required |
|---|---|---|---|
| API Endpoint | String | The API Endpoint used to connect to the Cloud Foundry web service. | Yes |
| Cloud Foundry CLI Path | String | Absolute path to the Cloud Foundry CLI executable file, specified if it is not already on the system path. | No |
| Cloud Foundry Password | Password | The password to authenticate with your Cloud Foundry instance. | Yes |
| Cloud Foundry User Name | String | The user name to authenticate with your Cloud Foundry instance. | Yes |
| Organization | String | The Cloud Foundry Organization that can be accessed according to the users permissions. | No |
| Space | String | The Cloud Foundry Space that provides the scope for services, applications, and containers. | No |
Log out of Cloud Foundry
Log out of the Cloud Foundry instance.
| Name | Type | Description | Required |
|---|---|---|---|
| Cloud Foundry CLI Path | String | Absolute path to the Cloud Foundry CLI executable file, specified if it is not already on the system path. | No |
Release IP Address
Release an IP address from the container cloud service instance. You must be logged in to Cloud Foundry before running this step by either running the Log in to Cloud Foundry step or by manually logging in on the agent computer.
| Name | Type | Description | Required |
|---|---|---|---|
| Cloud Foundry CLI Path | String | Absolute path to the Cloud Foundry CLI executable file, specified if it is not already on the system path. | No |
| IP Address | String | The floating IP address to release from the container cloud service. | Yes |
Remove Group
Remove a container group from the Bluemix repository.
| Name | Type | Description | Required |
|---|---|---|---|
| Cloud Foundry CLI Path | String | Absolute path to the Cloud Foundry CLI executable file, specified if it is not already on the system path. | No |
| Forced Removal | Boolean | Force the removal of a running or failed container. | No |
| Group Name | String | Name to assign to the group. Must start with a letter and can include uppercase letters, lowercase letters, numbers, periods, underscores, or hyphens. | Yes |
Request IP Address
Request a new floating IP address that can be used within your container cloud service instance. You must be logged into Cloud Foundry before running this step by either running the Log in to Cloud Foundry step or by manually logging in on the agent computer.
| Name | Type | Description | Required |
|---|---|---|---|
| Cloud Foundry CLI Path | String | Absolute path to the Cloud Foundry CLI executable file, specified if it is not already on the system path. | No |
Run Container
Start a new container from an image name or ID. You must be logged in to Cloud Foundry before running this step by either running the Log in to Cloud Foundry step or by manually logging in on the agent computer.
| Name | Type | Description | Required |
|---|---|---|---|
| Additional Arguments | String | Additional command-line arguments to pass when running this command (for example, memory 1024). | No |
| Bind Application | String | The name of the application to bind to the running container. | No |
| Cloud Foundry CLI Path | String | Absolute path to the Cloud Foundry CLI executable file, specified if it is not already on the system path. | No |
| Command | String | Command to run on the container (for example, export GROOVY_HOME=/opt/groovy). | No |
| Container Name | String | Name to assign to the running container. | No |
| Exposed Ports | Boolean | Automatically expose any ports specified in the images Dockerfile document for HTTP traffic. | No |
| Image Name/ID | String | The name or ID of the image to use for running the container. | Yes |
| Ports | String | Specify any ports to expose HTTP traffic on the running container. Split multiple ports by new line. | No |
Set Namespace
Set the namespace for the targeted organization. Be careful, this namespace cannot be unset. You must be logged in to Cloud Foundry before running this step by either running the Log in to Cloud Foundry step or by manually logging in on the agent computer.
| Name | Type | Description | Required |
|---|---|---|---|
| Cloud Foundry CLI Path | String | Absolute path to the Cloud Foundry CLI executable file, specified if it is not already on the system path. | No |
| Namespace | String | The namespace to be assigned to uniquely identify your organization in the Bluemix registry. The namespace must start with a lowercase letter and be 430 characters. You can use lowercase letters, numbers, and underscores. | No |
| On Failure | Enumeration: Fail Warn |
What to do when the namespace is already set for the organization. A setting of Fail will cause the step to fail and Warn will cause the step to warn but continue with process execution. | No |
Start Containers
Start stopped containers. You must be logged in to Cloud Foundry before running this step by either running the Log in to Cloud Foundry step or by manually logging in on the agent computer.
| Name | Type | Description | Required |
|---|---|---|---|
| Cloud Foundry CLI Path | String | Absolute path to the Cloud Foundry CLI executable file, specified if it is not already on the system path. | No |
| Container Names/IDs | String | The names or IDs of the containers to start. Multiple containers separated by new lines. | No |
Stop Containers
Stop running containers. You must be logged in to Cloud Foundry before running this step by either running the Log in to Cloud Foundry step or by manually logging in on the agent computer.
| Name | Type | Description | Required |
|---|---|---|---|
| Cloud Foundry CLI Path | String | Absolute path to the Cloud Foundry CLI executable file, specified if it is not already on the system path. | No |
| Container Name/ID | String | The names or IDs of the containers to start. Multiple containers separated by new lines. | No |
Unbind IP Address
Unbind the IP address allocated to the specified container. You must be logged in to Cloud Foundry before running this step by either running the Log in to Cloud Foundry step or by manually logging in on the agent computer.
| Name | Type | Description | Required |
|---|---|---|---|
| Cloud Foundry CLI Path | String | Absolute path to the Cloud Foundry CLI executable file, specified if it is not already on the system path. | No |
| Container Name/ID | String | The name or ID of the container from which to unbind the IP address. If not specified, the container that is currently bound to the specified IP address will be unbound. | No |
| IP Address | String | The floating IP address to release from the container cloud service. | Yes |
Uninstall IBM Containers Plug-in
Uninstall the IBM Containers plug-in.
| Name | Type | Description | Required |
|---|---|---|---|
| Cloud Foundry CLI Path | String | Absolute path to the Cloud Foundry CLI executable file, specified if it is not already on the system path. | No |
Update Group
Update specific options for a container group. You can update only one parameter at a time.
| Name | Type | Description | Required |
|---|---|---|---|
| Auto Recovery | String | Automatically restart failed container instances. | No |
| Cloud Foundry CLI Path | String | Absolute path to the Cloud Foundry CLI executable file, specified if it is not already on the system path. | No |
| Desired Instances | String | The number of required container instances. This is the number of containers by default. | No |
| Group Name | String | Name to assign to the group. Must start with a letter and can include uppercase letters, lowercase letters, numbers, periods, underscores, or hyphens. | Yes |
| Maximum Instances | String | The maximum number of container instances. | No |
| Minimum Instances | String | The minimum number of container instances. | No |
