Manage container software

Tag the Docker image

Whether deploying custom container software on either your IIoT Core Services or IIoT Gateway devices, first build and tag the Docker image in preparation for uploading it to IIoT Core Services.

Before you begin

Make sure Docker is installed and running on the machine where you will be building and tagging the Docker image.
Locate the IIoT Core Services IP address and Docker Trusted Registry port information. You need this information to build and tag the Docker image. See Port configuration requirements (Core Services).
Build an image (sample.tar, for example) using Docker CLI commands or obtain an image from a third party.
Check whether the Docker image is present on the machine using the command docker image -a.
If not, run the command docker image load -i <source_image>.tar (or tar.gz) to load an image from a .tar or .tar.gz file.

NoteIIoT Core Services currently only supports uploading .tar or .tar.gz files to the repository.

Procedure

Log in as a root user on the IIoT Core Services node.
Optionally, log in to your machine to tag the image locally.
Run the docker image -a command to show all images.
Find the image name and current tag for the image you want to use.
To tag the image, run the following command:
```
docker tag <source_image_name>:<old_tag> <cluster_fqdn>:32500/<target_image_name>:<new_tag>
```
Example:
```
docker tag httpd:test edge.hitachi-lumada.net:32500/httpd:latest
```
NoteDo not tag the image with the folder path /repository/pandora. This path is used for internal services.
To save the Docker image as a .tar or .tar.gz file, run the following command:
(Optionally, save as a tar.gz file.)
```
docker save -o <image_name>.tar <cluster_fqdn>:32500/<target_image_name>:<new_tag>
```
Example:
```
docker save -o httpd.tar edge.hitachi-lumada.net:32500/httpd:latest
```
NoteIf the Docker image was tagged and saved on a different machine than where you access IIoT Core Services, move the .tar or .tar.gz file to the machine used to access IIoT Core Services.

Upload container software

Now that you have built and tagged your container software, you can upload it to IIoT Core Services so that it is available to be deployed to your Core or Gateway devices.

Before you begin

Only .tar and .tar.gz file formats are supported.
Build and tag a Docker image with the Core IP address and Docker Trusted Registry port. For instructions, see Tag the Docker image.
Resume upload is not supported when using browsers from different machines, such as stop on machine A, then resume on machine B.
Resume upload is not supported when using different types of browsers on the same machine, such as first using Chrome, then Firefox.
The browser might log out automatically when you have been logged in for 30 minutes. You may experience upload failure and need to resume. Keycloak's default setting is 30 minutes, but this setting is configurable.

Resume upload is not supported when using the browser's incognito or private mode and then exiting all the browser sessions.

If you open a browser in incognito mode, upload something, are logged out, and then close all browser windows, then the upload won't resume. On the other hand, if two browsers are open in incognito mode and only one of the incognito sessions are open, then the other browser that is still open should be able to resume.

Procedure

In IIoT Core Services, select Repository Upload Software.
Use the Browse button to navigate to your Docker image and select Open.
Click Upload to upload the Docker image.
The software is uploaded successfully if it displays with a 'Successful' status.If the Status column displays the error, "Upload failed: unable to push uploaded file to registry", then the Docker image was tagged incorrectly. To resolve, verify that the core IP address and port correspond to the location where you are uploading the image.
NoteIf an image with the same image name and version as an existing image is uploaded, it will replace the existing image.
NoteIf you delete the Docker image using Docker CLI commands, the images still displays in the IIoT Core Services because it has not been removed from the Docker Trusted Registry.

Deploy container software in IIoT Core Services

You can deploy container software in IIoT Core Services by uploading an application configuration.

Before you begin

You must have a Kubernetes dashboard installed to deploy container software.
Verify that the software has been uploaded successfully to the software repository on the Repository tab in IIoT Core Services.
Ensure that deployment information is complete and available as a separate YAML file for uploading or for copying into IIoT Core Services.
Verify that the optional configuration and secret information is complete and available as separate YAML files for uploading into IIoT Core Services.

Procedure

Log on to your Kubernetes dashboard.
Create a namespace where your application can run.
Paste or upload the contents of your YAML file for namespace creation.
UDP and TCP are supported in the container port protocol.
NoteAs a best practice, do not deploy applications to the following existing namespaces: default, hiota, hiota-ui, kube-system, logging, monitoring.
This YAML example creates a namespace called custom-apps:
```
apiVersion: v1
kind: Namespace
metadata:
  name: custom-apps
```
Click UPLOAD.
Select the namespace you have deployed in the left-hand navigation of the Kubernetes dashboard in the Namespace list.
Deploy the YAML file for the application.
Paste or upload the contents of your YAML file for application deployment.

NoteMake sure the namespace in the deployment YAML file matches the namespace you’re in.
Click UPLOAD.
Use the same process for any supporting configuration and secret YAML files as described in Deploy software configurations or secrets on the Core device.

Results

Any pods for the deployed software are displayed in the namespace where the software was deployed. You may validate your application is running and deployed by inspecting the Deployments tab in the left-hand navigation of the dashboard. Your deployment should be running as indicated by a green check mark.

Update container software in IIoT Core Services

You can update container software in IIoT Core Services by editing the application configuration.

Before you begin

The software must be available in the repository.

Procedure

Log on to your Kubernetes dashboard.
In the Namespace list, select the namespace where your container software is deployed.
Under deployments, select to edit the YAML for the relevant pod.
The container configuration appears in the editor.
Make the necessary edits and click UPDATE.

Deploying container software on a gateway

You can deploy software to single or multiple gateway devices.

Prerequisites for deploying software on a gateway

Observe the following prerequisites to successfully deploy container software to a gateway.

The container software must be uploaded to the Docker Trusted Registry before you can deploy.
The deployment information should be complete and available as a separate YAML file for uploading, or for copying into IIoT Core Services.
The optional configuration and secret information should be complete and available as separate YAML files for uploading into IIoT Core Services.
To monitor select information, such as CPU or memory, or for troubleshooting, you can mount your volume in a different folder than the default location. However, as a best practice for security, do not change the default volume mounts which the containers write to for persisting data:
/var/lumada-edge/volumes/default-gateway/{CONTAINER_NAME}/dynamic/{VOLUME_NAME}
NoteOnly hostPath is supported for persisting volumes on a gateway.
NoteOnly deployment is supported in IIoT Core Services. DaemonSet is not supported.

Deploy software to one or more gateways

You can deploy software to one or more gateway devices.

Procedure

In the IIoT Core Services UI, select the Device tab.
Select one or more gateway devices using the check boxes.
You can only select devices that are online and in Ready state.
Select Deploy Deploy Software.
In the Software section, find the software container you want to deploy and copy the path to the clipboard.
Update the deployment YAML with the copied path of the container image.
In the Upload Files section, paste your updated deployment YAML file into the edit window.
(Optional) In the Upload secret and configuration files (optional) text box, add the following files:
- Configuration YAML: Contains configuration settings that are needed to deploy software, or parameters that can customize your installation.
- Secret YAML: Stores and manages sensitive information, such as passwords, OAuth tokens, and SSH keys.
Click Deploy.
The Deployment tab appears to show the status of the deployment.

Deploy software to a device group

You can deploy software to a group of gateway devices.

Procedure

In the IIoT Core Services UI, select the Device tab, then the Device Group tab.
Select a device group.
The Details sub-tab opens.
Select Deploy Deploy Software to deploy software to the device group.
In the Software section, find the software container you want to deploy and copy the path to the clipboard.
Update your deployment YAML with the copied path of the container image.
In the Upload Files section, paste your updated deployment YAML file into the edit window.
(Optional) In the Upload secret and configuration files (optional) text box, add the following files:
- Configuration YAML: Contains configuration settings that are needed to deploy software, or parameters that can customize your installation.
- Secret YAML: Stores and manages sensitive information, such as passwords, OAuth tokens, and SSH keys.
Click Deploy.
The Deployment tab shows the status of the deployment.

Update container software on a gateway

You can update container software on a gateway device.

Build, tag, and upload your container software to DTR.
See Tag the Docker image and Upload container software for details.
In the IIoT Core Services UI, select the Device tab.
Select a device name to go to the Device Details page.
Select the Software Updates tab to view the list of container software available on the selected gateway device.
From the Actions menu ( ) next to the deployment YAML file that you want to update, select View/Edit.
Update the deployment YAML if needed and click Deploy.
The container restarts.

Delete container software on a gateway

You can delete container software from a gateway device.

Procedure

In the IIoT Core Services UI, select the Device tab.
Select a device name.
Select the Software Updates tab to view the list of deployment YAML files available on the selected gateway device.
From the Actions menu ( ) next to the YAML file that you want to delete, select Delete.

Results

The deployment is removed from the gateway device and the gateway is reset to default settings.