MindSphere Registry 4 Container Registry...orchestration engine are compatible and can be easily migrated to MindSphere to participate in the MindSphere ecosystem. Container Registry

MindSphere

Container Registry

System Manual

07/2021V1801.Jul/2021.1

Document history 1Introduction 2Prerequisites 3User rights in Container Registry 4Accessing Container Registry 5

Projects 6Administration 7

Legal informationWarning notice system

This manual contains notices you have to observe in order to ensure your personal safety, as well as to prevent damage to property. The notices referring to your personal safety are highlighted in the manual by a safety alert symbol, notices referring only to property damage have no safety alert symbol. These notices shown below are graded according to the degree of danger.

DANGERindicates that death or severe personal injury will result if proper precautions are not taken.

WARNINGindicates that death or severe personal injury may result if proper precautions are not taken.

CAUTIONindicates that minor personal injury can result if proper precautions are not taken.

NOTICEindicates that property damage can result if proper precautions are not taken.If more than one degree of danger is present, the warning notice representing the highest degree of danger will be used. A notice warning of injury to persons with a safety alert symbol may also include a warning relating to property damage.

Qualified PersonnelThe product/system described in this documentation may be operated only by personnel qualified for the specific task in accordance with the relevant documentation, in particular its warning notices and safety instructions. Qualified personnel are those who, based on their training and experience, are capable of identifying risks and avoiding potential hazards when working with these products/systems.

Proper use of Siemens productsNote the following:

WARNINGSiemens products may only be used for the applications described in the catalog and in the relevant technical documentation. If products and components from other manufacturers are used, these must be recommended or approved by Siemens. Proper transport, storage, installation, assembly, commissioning, operation and maintenance are required to ensure that the products operate safely and without any problems. The permissible ambient conditions must be complied with. The information in the relevant documentation must be observed.

TrademarksAll names identified by ® are registered trademarks of Siemens AG. The remaining trademarks in this publication may be trademarks whose use by third parties for their own purposes could violate the rights of the owner.

Disclaimer of LiabilityWe have reviewed the contents of this publication to ensure consistency with the hardware and software described. Since variance cannot be precluded entirely, we cannot guarantee full consistency. However, the information in this publication is reviewed regularly and any necessary corrections are included in subsequent editions.

Siemens AGDigital IndustriesPostfach 48 4890026 NÜRNBERGGERMANY

V1801.Jul/2021.1Ⓟ 07/2021 Subject to change

Copyright © Siemens AG 2021.All rights reserved

Table of contents

1 Document history .................................................................................................................................. 72 Introduction ........................................................................................................................................... 93 Prerequisites ........................................................................................................................................ 114 User rights in Container Registry......................................................................................................... 135 Accessing Container Registry .............................................................................................................. 156 Projects ................................................................................................................................................ 17

6.1 Container Registry project .................................................................................................. 176.2 Pushing images into Harbor ............................................................................................... 286.3 Managing images .............................................................................................................. 296.4 Pulling images from Harbor................................................................................................ 296.5 Logs .................................................................................................................................. 31

7 Administration..................................................................................................................................... 337.1 Overview........................................................................................................................... 337.2 Users ................................................................................................................................. 337.3 Managing registries ........................................................................................................... 347.4 Configuring replications ..................................................................................................... 377.5 Managing Global Labels ..................................................................................................... 417.6 Project Quotas ................................................................................................................... 417.7 Interrogation Services ........................................................................................................ 427.8 Garbage Collection ............................................................................................................ 447.9 Configuration..................................................................................................................... 46

Container RegistrySystem Manual, 07/2021, V1801.Jul/2021.1 3

Table of contents

Container Registry4 System Manual, 07/2021, V1801.Jul/2021.1

Container Registry enables customers to accelerate development, simplify storing and managing images, and reduce operations efforts. It offers an effective way to deploy, manage, and scale containerized solutions.This system manual enables you to start with Container Registry. It leads you through the process of creating projects, managing users, managing registries and replications, managing project quotas, managing configurations, scanning vulnerabilities, and garbage collection (free-up space) processes.



Document history 1Version Date Changes LinkV1801.Jul/2021.1 2021-07-10 Added robot account info Container Registry project (Page 17)V1801.Feb/2021.1 2021-02-08 Updated content and images

throughout the document.

V1801.Jun/2020.1 2020-06-13 New document created for Contain‐er Registry


Document history


Introduction 2Introduction

Container Registry enables customers to accelerate development, simplify storing and managing images, and reduce operations efforts. It offers an effective way to deploy, manage, and scale containerized solutions. Applications running on Kubernetes or any container orchestration engine are compatible and can be easily migrated to MindSphere to participate in the MindSphere ecosystem.Container Registry application is a part of the MindSphere platform, and you can access it from the MindSphere launchpad. A third-party software called Harbor is integrated into Container Registry. It allows the customers to deploy their applications quickly and scale them as required.Using the Container Registry application, you can:• Create projects, View projects and its details• Create Robot Accounts• Tag and push images into Container Registry• View log information of operations performed in Container Registry

– Global log: Logs that include all projects and repositories– Project log: Project specific logs

• Manage Labels– Global labels: Labels applicable for all projects within a tenant– Project labels: Project specific Labels

• Create, edit and delete registry endpoints and replication rules• Configure global settings• Allocate project quotas• Schedule Garbage collection and view history• Enable content trust• Interrogation services such as image scanners and Vulnerability checks.

HarborHarbor is a third-party software integrated into MindSphere. It is an open-source trusted cloud native registry and it allows you to store and manage images.For more information, refer to the Harbor user guide (https://goharbor.io/docs/1.10/).


https://goharbor.io/docs/1.10/

Introduction


Prerequisites 3Container Registry is a MindSphere App that can be bought via MindSphere store for developer and operator tenants. However, it is not available for IoT tenants. Once the application is deployed to the tenant, all existing tenant admins will receive the Container Registry admin role. Thereafter, no more automated provisioning will be performed, which means, every new tenant admin or any other user working with Container Registry has to be manually assigned the correct role.For other prerequisites, refer to the Harbor Installation guide (https://goharbor.io/docs/1.10/install-config/).


https://goharbor.io/docs/1.10/install-config/

https://goharbor.io/docs/1.10/install-config/

Prerequisites


User rights in Container Registry 4The user rights depend on the following user roles:• mdsp:core:mcradvanced.admin• mdsp:core:mcradvanced.developerThe following table gives an overview of the permissions for Admin and Developer roles:

Right RolesAdmin Developer

Create projects ✓ ✓*Delete projects ✓ ✓**Push images into harbor ✓ ✓Pull images from harbor ✓ ✓View logs ✓ ✓Manage registries ✓ -Configure replications ✓ -Configure system settings ✓ -Manage Labels ✓ -Edit project Quotas ✓ -Manage image scanners ✓ -Scan vulnerabilities ✓ -Garbage collection ✓ -

* Valid only if the Admin selects the “Everyone” option from the “Project creation” drop-down menu under “Administration>Configuration>System Settings”.** Developer can delete a project if the access level is “Project Admin” for that project.For more information on roles, see Settings documentation (https://documentation.mindsphere.io/resources/html/settings/en-US/index.html).


https://documentation.mindsphere.io/resources/html/settings/en-US/index.html

https://documentation.mindsphere.io/resources/html/settings/en-US/index.html

User rights in Container Registry


Accessing Container Registry 5To launch the application, click on the Container Registry icon on the MindSphere Launchpad.

DisclaimerWhen you launch the Container Registry application for the first time, you will be prompted to read and accept a disclaimer. Accept disclaimer to access the Container Registry application.

If you do not accept the disclaimer, you will not be directed to the application and instead, you will be redirected to the MindSphere Launchpad.


User interfaceWhen you launch the Container Registry application, the following user interface is displayed:

① MindSphere OS Bar② Navigation pane. It provides the following options:

• Projects• Logs• Administration

③ Detailed view pane. It shows details about the option selected in the navigation pane.④ Provides a list of all the local events, running events, and failed events.

Accessing Container Registry


Projects 66.1 Container Registry project

A project is a collection of repositories. Each repository contains all the images pushed into it. When you launch Container Registry, the "Projects" screen is displayed. On this screen, the project with the name same as your tenant name is displayed. The following screenshot shows the "Projects" screen:

① Navigation pane.② Option to add new projects.③ Table displays the details of the project.④ Information area showing the number of private and public projects and repositories.⑤ Provides tabs to view a list of all the local events, running events, and failed events.

Click on a project to view/configure it further. The following sections describe important navigation tabs on this screen.


Creating New projects1. Click the “+ New Project“ button in the “Projects” menu.

The following pop-up window appears.

2. Enter an appropriate project name.3. If the “Access level” “Public” checkbox is enabled, any Harbor user will have read permission

to the repositories under this project.4. Define the number of artifacts using the "Count quota" option. For unlimited quota, enter '-1'.5. Define the storage consumption quota and select the storage unit using the “Storage quota”

option. For unlimited quota, enter '-1'.6. Click “Ok” to create a new project. Administrators can delete any project available within the tenant. A developer can delete a project if the access level is "Project Admin" for that project.

Projects6.1 Container Registry project


SummaryThe summary tab shows information such as the number of repositories, Helm Charts, members, and the Quotas allocated for a selected project.

RepositoriesIn this tab, a table of repositories within a selected project is displayed.• To download the registry certification, click "REGISTRY CERTIFICATE".• To copy the syntax to tag or push an image, use the "PUSH IMAGE DOCKER COMMAND" list.• To display the details of repositories as cards, click on the icon.



Helm ChartsHelm is a package manager for Kubernetes, and it uses a packaging format called charts. This tab shows information on all existing helm charts within a selected project.

• To upload a new Chart, click "UPLOAD", browse the chart file and provenance file from your file system, and click "UPLOAD".

• You can download an existing Chart using the "DOWNLOAD" button. You can also remove a selected Chart file using the "DELETE" button.



MembersThis tab shows all the members of a project and their roles.• To add a member, click "USER", enter the member name, select the required role, and then

click "OK". You can only add users on the same MindSphere tenant with the role mdsp:core:mcradvanced.developer to the project. By default, the mdsp:core:mcradvanced.admin will have access to the project.

• To update role(s), select the member(s), click "ACTIONS", and then select the required role.Similarly, you can remove the selected member(s).



LabelsHarbor provides two types of labels to isolate different types of resources:• Global Level Label: Managed by Harbor system administrators and used to manage the

images of the whole system. They can be added to images under any project. For more information on Global level label, see Section Configuration (Page 46).

• Project Level Label: Managed by project administrators under a project and can only be added to the images of the project. You can "EDIT" or "DELETE" a selected label using the corresponding options available in the "Labels" tab.

LogsThis tab shows all the recorded logs. It shows username, repository name, version number, type of operation, and the time when the operation was performed.

You can filter the logs based on operations and dates using the "ADVANCED" search option.



Robot AccountsContainer Registry Admins can create Robot Accounts and these accounts are intended to perform docker push/pull operations using a token.

• To create a robot account, click "NEW ROBOT ACCOUNT", enter a name and a description, select permission(s), and then click "SAVE".



NoteThe "pull" permission for Image is enabled by default.

• You can disable or delete a robot account using the "ACTION" list.



Tag RetentionUsing this feature, you can define rules that govern how many artifacts of a given repository to retain, or for how long to retain certain artifacts.

For more information such as add new rule, edit schedule, test rules, refer to the Harbor documentation (https://goharbor.io/docs/1.10/working-with-projects/working-with-images/create-tag-retention-rules/).

Tag ImmutabilityThe Tag Immutability feature allows you to configure tag immutability at the project level so that artifacts with certain tags cannot be pushed into Harbor if their tags match existing tags. This feature ensures that an immutable tagged image can neither be deleted nor be altered by re-pushing, re-tagging, or replicating.

For more details such as add a new rule, refer to the Harbor documentation (https://goharbor.io/docs/1.10/working-with-projects/working-with-images/create-tag-immutability-rules/).



https://goharbor.io/docs/1.10/working-with-projects/working-with-images/create-tag-retention-rules/

https://goharbor.io/docs/1.10/working-with-projects/working-with-images/create-tag-retention-rules/

https://goharbor.io/docs/1.10/working-with-projects/working-with-images/create-tag-immutability-rules/

https://goharbor.io/docs/1.10/working-with-projects/working-with-images/create-tag-immutability-rules/

WebhooksWithin this tab, you can configure webhooks so that the Harbor notifies the webhook endpoint of certain events that occur in a project, including push, pull, deletion of images and Helm charts, image scanning, and vulnerability discoveries.

ScannerThis tab shows the available Scanners within a selected project.



ConfigurationYou can configure projects so that the images with vulnerabilities cannot be run, and automatically scan images as soon as they are pushed into the project.

• To make all repositories under the project accessible to everyone, select the “Public” checkbox.

• To prevent un-signed images under the project from being pulled, select the “Enable content trust” checkbox.

• To prevent vulnerable images under the project from being pulled, select the “Prevent vulnerable images from running” checkbox and change the severity level of vulnerabilities. Images cannot be pulled if their level equals to or higher than the currently selected level.



• To activate an immediate vulnerability scan on new images that are pushed to the project, select the “Automatically scan images on push” check box.NoteIf the “Automatically scan images on push” feature is enabled, new internal robot accounts will be created and their activities are tracked under "Projects" > "Logs".

• To ignore certain Common Vulnerabilities and Exposures (CVE), create a whitelist of CVEs at the project level or copy from the system. You can also define the expiry of the whitelist item.

6.2 Pushing images into HarborThis section explains how to tag and push the docker images into Harbor.

Prerequisite• Docker client is installed on your machine.• The user must have an appropriate role.• The required robot account is already created.• Make sure the project to which you are pushing the image is available on Harbor.

ProcedureTo push an image into Harbor, follow these steps:1. Log in to Docker client.

docker login pun8cr01.registry.eu1.mindsphere.io -u ‘<RobotAccountID>’ -p ‘<password>’

2. Tag your new application build.docker tag <ApplicationName> <TenantURL>/<Application>:<BuildInfo>

3. Push your tagged image to the repository.docker push <ApplicationName> <TenantURL>/<Application>:<BuildInfo>

NoteTag and push command syntaxYou can copy the command syntax to tag an image or push an image from the "PUSH IMAGE" list in the "Repositories" tab.

Projects6.2 Pushing images into Harbor


ResultThe newly added image is displayed under the appropriate repository with details as shown in the following screenshot.

6.3 Managing imagesEach repository contains all the images pushed into it. To view the image(s), click on the selected repository.

User interfaceThe following screenshot shows an image already pushed into Harbor:

6.4 Pulling images from HarborThis section explains how to pull an image from Harbor.

Prerequisites• Docker client is installed on your machine.• The user must have an appropriate role.

Projects6.4 Pulling images from Harbor


• The required robot account is already created.• Make sure the application and version that you want to pull is available in Harbor.

ProcedureTo pull an image into Harbor, follow these steps:1. Log in to Docker client.

docker login pun8cr01.registry.eu1.mindsphere.io -u ‘<RobotAccountID>’ -p ‘<password>’

2. Tag your new application build.docker tag <ApplicationName> <TenantURL>/<Application>:<BuildInfo>

3. Pull your tagged image to the repository.docker pull <ApplicationName> <TenantURL>/<Application>:<BuildInfo>

NotePull command syntaxYou can copy the syntax to pull an image from the "Pull Command" column in the "Images" tab.

ResultThe pulled image is downloaded to your local machine.

Projects6.4 Pulling images from Harbor


6.5 LogsTo view all the recorded logs, select "Logs" on the navigation pane. The "Logs" screen shows username, repository name, version number, type of operation, and the time when the operation was performed.

Projects6.5 Logs


Projects6.5 Logs


Administration 77.1 Overview

The "Administration" application enables system administrators to configure and maintain Container Registry after deployment. The following sections will walk you through all functionalities of the "Administration" application in detail.

7.2 UsersYou can view all Container Registry users in the "Users" screen. However, any actions such as create, delete or reset password are not permitted.

The following error message appears when you try to create a new user.


7.3 Managing registriesReplication allows users to replicate resources between Harbor and non-Harbor registries, in both pull or push mode.

Administration7.3 Managing registries


A registry endpoint must exist before you replicate image repositories from one instance of Harbor to another Harbor or non-Harbor registry. Proceed as follows to create a new registry endpoint:1. Click “Registries“ in the “Administration” menu in the navigator.2. Click the “+ New Endpoint” button.

The following pop-up window appears:



3. Select the type of registry to set up as a replication endpoint from the “Provider” drop-down menu.The endpoint can be another Harbor instance or a non-Harbor registry.

4. Enter a suitable name and description for the new replication endpoint.5. Enter the full URL of the registry to set up as a replication endpoint.

NoteThe registry must exist and be running before you create the endpoint.

6. Enter the Access ID and Access Secret for the endpoint registry instance.7. Optionally, select the "Verify Remote Cert" check box.

Deselect the check box if the remote registry uses a self-signed or untrusted certificate.8. Click “Test Connection”.9. When the connection is successfully tested, click “OK”.To edit or delete registries, select the registry and click “Edit” or “Delete”. Only registries that are not referenced by any rules can be deleted.



7.4 Configuring replicationsA replication endpoint must exist before you create a replication rule. To create an endpoint, see Managing registries (Page 34).

Creating a Replication Rule1. Click “Replications“ in the “Administration” menu in the navigator.2. Click the “+ New Replication Rule” button.

The following pop-up window appears.3. Provide a name and description for the replication rule.4. Select “Push-based” or “Pull-based” replication mode, depending on whether you want to

replicate images to or from the remote registry.

Administration7.4 Configuring replications


5. If the pull-based replication mode is selected, use the “Source Registry” drop-down menu to select from the configured replication endpoints.

6. If the push-based replication mode is selected, use the “Destination Registry” drop-down menu to select from the configured replication endpoints.



7. For “Source resource filter”, identify the images to replicate.

Name: Replicate resources with a given name by entering an image name or fragment.Tag: Replicate resources with a given tag by entering a tag name or fragment.Label: Replicate resources with a given Label.Resource: Replicate images, charts, or both.The name filter and tag filters support the following patterns:

Pattern Description* Matches any sequence of non-separator characters /.** Matches any sequence of characters, including path separators /.? Matches any single non-separator character /.{alt1,...} Matches a sequence of characters if one of the comma-separated alternatives

matches.

8. Enter the name of the namespace in which to replicate resources in the “Destination namespace” text box.NoteIf you do not enter a namespace, resources are placed in the same namespace as in the source registry.

9. Use the “Trigger Mode” drop-down menu to select how and when to run the rule.

Trigger Mode DescriptionManual Replicate the resources manually when needed. Note that Deletion opera‐

tions are not replicated.Scheduled Replicate the resources periodically by defining a cron job. Note that Deletion

operations are not replicated.Event based When a new resource is pushed to the project or an image is retagged, it is

replicated to the remote registry immediately. If you select the “Delete re‐mote resources when locally deleted”, if you delete an image, it is automati‐cally deleted from the replication target.Note: You can filter images for replication based on the labels that are applied to the images. However, changing a label on an image does not trigger rep‐lication. Event-based replication is limited to pushing, retagging, and delet‐ing images.

10.Optionally, select the “Override” and checkbox.11.Click “Save” to create the replication rule.To edit or delete a replication rule, select the replication rule and click “Edit” or “Delete”. Only rules which have no executions in progress can be edited deleted.



Running Replication manually1. Select the replication rule using the checkbox from the “Replications” tab.2. Click the “Replicate” button.

A pop-up window appears to confirm the replication.3. Click “Replicate” in the confirm window.

The resources to which the rule is applied start to replicate from the source registry to the destination immediately.

4. Click the rule to see its execution status.

5. Click the ID of the execution to see the details of the replication and the task list. The count of "IN PROGRESS" status in the summary includes both Pending and In Progress tasks.

6. Optionally, click "STOP" to stop the replication.7. Click the log icon to see detailed information about the replication task.



7.5 Managing Global LabelsHarbor provides two types of labels to isolate different types of resources:• Project Level Label: Managed by project administrators under a project and can only be added

to the images of the project. For more information, see Section Container Registry project (Page 17).

• Global Level Label: Managed by Harbor system administrators and used to manage the images of the whole system. They can be added to images under any project.

A new label can be created using the “+ New Label” button and entering an appropriate label name, description, and label color. To edit or delete a label, select the label and click “Edit” or “Delete”.For more information about the Labels, see Harbor user guide (https://goharbor.io/docs/2.1.0/working-with-projects/working-with-images/create-labels/#managing-global-labels).

7.6 Project QuotasIn this tab you can view and edit the quotas such as the number of artifacts or the storage capacity that a project can consume.

① Edit quotas for individual projects② Edit default quotas

Administration7.6 Project Quotas


https://goharbor.io/docs/2.1.0/working-with-projects/working-with-images/create-labels/#managing-global-labels

https://goharbor.io/docs/2.1.0/working-with-projects/working-with-images/create-labels/#managing-global-labels

You can set quotas that apply to all projects globally (Default Quotas) or on individual projects. For unlimited quota, enter value '-1'.

NoteDefault quota is not applied to projects that already existed before you set it.

7.7 Interrogation Services

ScannersThis feature allows you to connect Harbor to additional vulnerability scanners. The scanner must expose an API endpoint to allow Harbor to trigger the scan process or get reports.

Administration7.7 Interrogation Services


Proceed as follows to add a new scanner:1. Click "+ NEW SCANNER" from the "Scanners" tab.

The following window appears.

2. Enter project name and description.3. Enter the API endpoint address.4. Select the Authorization mode from the drop-down.

– None: The scanner allows all connections without any security. – Basic: Enter a username and password for an account that can connect to the scanner. – Bearer: Paste the contents of a bearer token in the Token text box. – APIKey: Paste the contents of an API key for the scanner in the APIKey text box.

5. Optionally select "Skip certificate verification" if the scanner uses a self-signed or untrusted certificate.

6. Optionally select "Use internal registry address" if the scanner should connect to Harbor using an internal network address rather than its external URL.NoteTo use this option, the scanner must be deployed in a network that allows the scanner to reach Harbor via Harbor’s internal network.

7. Click "Test Connection" to make sure that Harbor can connect successfully to the scanner.8. Click "Add" to connect Harbor to the scanner.If you configure multiple scanners, select one and click "SET AS DEFAULT" to designate it as the default scanner.To Disable, Edit or Delete scanner(s), use the corresponding options from the "ACTION" menu.

Administration7.7 Interrogation Services


VulnerabilityStatic analysis of vulnerabilities in images can be performed using the Vulnerability Scanning functionality. You can manually initiate scanning on a particular image, or on all images in Harbor. Additionally, you can set a policy to automatically scan all the images at specific intervals. However, set the automatic scan policy to the maximum up to "Daily". Also, make sure to enable the "Automatically scan images on push" check box from "Projects > Configuration". For more information, refer to the Configuration section in Container Registry project (Page 17).

7.8 Garbage CollectionWhen images are deleted from Harbor, space is not automatically freed-up. A garbage collection must be performed to free-up space by removing blobs (binary large objects) that are no longer referenced by a manifest from the file system.To avoid triggering the garbage collection process too frequently, the availability of the "GC Now" button is restricted. Garbage collection can be only run once per minute.

Administration7.8 Garbage Collection


Use the drop-down menu (visible once the "Edit" button is clicked) to select how often to run garbage collection.

The "History" tab shows the 10 most recent Garbage Collection runs.

Administration7.8 Garbage Collection


7.9 ConfigurationYou can configure Harbor to connect to an email server, set the registry in read-only mode, and configure Harbor so that only system administrators can create projects.

Administration7.9 Configuration


Configuring AuthenticationThe user is not permitted to select the authentication mode, therefore the "Auth Mode" selection under the "Authentication" tab is disabled. In addition, the user is not permitted to save any changes made to the "Allow Self-Registration" checkbox, which means, the "Save" button is also disabled.



Configuring Email ServerSince the local user creation is not allowed, the email functionality is disabled. Any changes made to the "Email" tab will not be saved, an error message appears.



Configuring System SettingsUse the “Project Creation” drop-down menu to set which users can create projects. Select “Everyone” to allow all users to create projects. Select “Admin Only” to allow only users with the Harbor system administrator role to create projects.

You can set Harbor to read-only mode by enabling the “Repository Read Only” checkbox. In read-only mode, Harbor allows “Docker pull” but prevents “Docker push” and the deletion of repositories and tags.You can ignore certain Common Vulnerabilities and Exposures (CVE) by creating a whitelist of CVEs. You can also define the expiry of the whitelist item.





Documents

MindSphere Registry 4 Container Registry...orchestration engine are compatible and can be easily migrated to MindSphere to participate in the MindSphere ecosystem. Container Registry