More content reorg

docs/harbor-doc-reorg/_index.md

@@ -71,6 +71,7 @@ This section describes how users with the developer, master, and project adminis
       - **[Create Labels](working_with_projects/create_labels.md)**
       - **[Retag Images](working_with_projects/retagging_images.md) **
       - [Create Tag Retention Rules](working_with_projects/create_tag_retention_rules.md)
+      - [Create Tag Immutability  Rules](working_with_projects/create_tag_immutability_rules.md)
       - [Manage Kubernetes Packages with Helm Charts](working_with_projects/managing_helm_charts.md)
 
 ## Build, Customize, and Contribute to Harbor

docs/harbor-doc-reorg/working_with_projects/create_robot_accounts.md

@@ -1,38 +1,53 @@
 # Create Robot Accounts
 
-Robot Accounts are accounts created by project admins that are intended for automated operations. They have the following limitations:
+You can create robot accounts to run automated operations. Robot accounts have the following limitations:
 
-1, Robot Accounts cannot login Harbor portal
-2, Robot Accounts can only perform operations by using the Docker and Helm CLIs.
+1. Robot Accounts cannot log in to the Harbor interface.
+1. Robot Accounts can only perform operations by using the Docker and Helm CLIs.
 
 ### Add a Robot Account
-If you are a project admin, you can create a Robot Account by clicking "New Robot Account" in the `Robot Accounts` tab of a project, and enter a name, a description, and grant permission to the account to push and pull images and Helm charts.
-![add_robot_account](../img/robotaccount/add_robot_account.png)
 
-![add_robot_account](../img/robotaccount/add_robot_account_2.png)
+1. Log in to the Harbor interface with an account that has at least project administrator privileges.
+1. Go to **Projects**, select a project, and select **Robot Accounts**.
 
-> **NOTE:** The name will become `robot$<accountname>` and will be used to distinguish a robot account from a normal harbor user.
+   ![Robot accounts](../img/add_robot_account.png)
+1. Click **New Robot Account**.
+1. Enter a name and an optional description for this robot account.
+1. Grant permission to the robot account to push images and to push and pull Helm charts.
 
-![copy_robot_account_token](../img/robotaccount/copy_robot_account_token.png)
-As Harbor doesn't store your account token, please make sure to copy it in the pop up dialog after creating, otherwise, there is no way to get it from Harbor.
+   Robot accounts can always pull images, so you cannot deselect this option.
+   
+   ![Add a robot account](../img/add_robot_account_2.png)
+1. Click **Save**.
+1. In the confirmation window, click **Export to File** to download the access token as a JSON file, or click the clipboard icon to copy its contents to the clipboard.
+   
+   ![copy_robot_account_token](../img/copy_robot_account_token.png)
 
-### Configure duration of robot account
-If you are a system admin, you can configure the robot account token duration in days. 
-![set_robot_account_token_duration](../img/robotaccount/set_robot_account_token_duration.png)
+   **IMPORTANT**: Harbor does not store robot account tokens, so you must either download the token JSON or copy and paste its contents into a text file. There is no way to get the token from Harbor after you have created the robot account.
+   
+   The new robot account appears as `robot$account_name` in the list of robot accounts. The `robot$` prefix makes it easily distinguishable from a normal Harbor user account.
 
-### Authenticate with a robot account
-To authenticate with a Robot Account, use `docker login` as below,
+   ![New robot account](../img/new_robot_account.png)
+1. To delete or disable a robot account, select the account in the list, and select **Disable account** or **Delete** from the Action drop-down menu.
 
-```
-docker login harbor.io
-Username: robot$accountname
-Password: Thepasswordgeneratedbyprojectadmin
-```
+   ![Disable or delete a robot account](../img/disable_delete_robot_account.png)
 
-### Disable a robot account
-If you are a project admin, you can disable a Robot Account by clicking "Disable Account" in the `Robot Accounts` tab of a project.
-![disable_robot_account](../img/robotaccount/disable_delete_robot_account.png)
+### Configure the Expiry Period of Robot Accounts
 
-### Delete a robot account
-If you are a project admin, you can delete a Robot Account by clicking "Delete" in the `Robot Accounts` tab of a project.
-![delete_robot_account](../img/robotaccount/disable_delete_robot_account.png)
+By default, robot accounts expire after 30 days. You can set a longer or shorter lifespan for robot accounts by modifying the expiry period for robot account tokens. The expiry period applies to all robot accounts in all projects.
+
+1. Log in to the Harbor interface with an account that has Harbor system administrator privileges.
+1. Go to **Configuration** and select **System Settings**.
+1. In the **Robot Token Expiration (Days)** row, modify the number of days after which robot account tokens expire. 
+   
+   ![Set robot account token expiry](../img/set_robot_account_token_duration.png)
+
+### Authenticate with a Robot Account
+
+To use a robot account in an automated process, for example a script, use `docker login` and provide the credentials of the robot account.
+
+<pre>
+docker login <i>harbor_address</i>
+Username: robot$<i>account_name</i>
+Password: <i>robot_account_token</i>
+</pre>

docs/harbor-doc-reorg/working_with_projects/create_tag_immutability_rules.md

@@ -0,0 +1,53 @@
+# Tag Immutability Rules
+
+By default, users can repeatedly push an image with the same tag to repositories in Harbor. This causes the previous image to effectively be overwritten with each push, in that the tag now points to a different image and the image that previously used the tag now becomes tagless. This is due to the Docker implementation, that does not enforce the mapping between an image tag and the image digest. This can be undesirable in certain cases, because the tag can no longer be trusted to identify the image version. The sha256 digest remains reliable and always points to the same build, but it is not rendered in a human-readable format.  
+
+Moreover, the Docker implementation requires that deleting a tag results in the deletion of all other tags that point to the same digest, causing unwanted image deletions.
+
+To prevent this, Harbor allows you to configure tag immutability at the project level, so that images with certain tags cannot be pushed into Harbor if their tags match existing tags. This prevents existing images from being overwritten. Tag immutability guarantees that an immutable tagged image cannot be deleted, and cannot be altered through repushing, retagging, or replication. 
+
+Immutability rules use `OR` logic, so if you set multiple rules and a tag is matched by any of those rules, it is marked as immutable. 
+
+## How Immutable Tags Prevent Tag Deletion
+
+Tags that share a common digest cannot be deleted even if only a single tag is configured as immutable. For example:
+
+1. In a project, set an immutable tag rule that matches the image and tag `hello-world:v1`.
+1. In the Docker client, pull `hello-world:v1` and retag it to `hello-world:v2`.
+1. Push `hello-world:v2` to the same project.
+1. In the Harbor interface, attempt to delete `hello-world:v2`.
+
+In this case, you cannot delete `hello-world:v2` because it shares the sha256 digest with `hello-world:v1`, and `hello-world:v1` is an immutable tag. 
+
+## Create a Tag Immutability Rule
+
+1. Log in to the Harbor interface with an account that has at least project administrator privileges.
+1. Go to **Projects**, select a project, and select **Tag Immutability**.
+
+   ![Add an immutability rule](../img/tag-immutability.png)
+1. Click **Add Rule**.
+
+   - In the **Respositories** row, enter a comma-separated list of repositories to which to either apply or exclude from the rule by selecting either **matching** or **excluding** from the drop-down menu.
+   - In the **Tags** row, enter a comma-separated list of tags to which to either apply or exclude from the rule by selecting either **matching** or **excluding** from the drop-down menu.
+ 
+   ![Add an immutability rule](../img/add-immutability-rule.png)
+1. Click **Add** to save the rule.
+
+   You can add a maximum of 15 immutability rules per project. 
+
+   After you add a rule, any tags that are identified by the rule are marked **Immutable** in the Repositories tab.
+1. To modify an existing rule, use the **Action** drop-down menu next to a rule to disable, edit, or delete that rule. 
+
+   ![Immutability rules](../img/edit-tag-immutability.png)
+
+## Example
+
+To make all tags for all repositories in the project immutable, set the following options:
+
+- Set **For the respositories** to **matching** and enter `**`.
+- Set **Tags** to **matching** and enter `**`.
+
+To allow the tags `rc`, `test`, and `nightly` to be overwritten but make all other tags immutable, set the following options:
+
+- Set **For the respositories** to **matching** and enter `**`.
+- Set **Tags** to **excluding** and enter `rc,test,nightly`.

docs/harbor-doc-reorg/working_with_projects/managing_helm_charts.md

@@ -1,36 +1,35 @@
-# Manage Kubernetes Packages with Helm Charts
-
+# Managing Helm Charts
 [Helm](https://helm.sh) is a package manager for [Kubernetes](https://kubernetes.io). Helm uses a packaging format called [charts](https://docs.helm.sh/developing_charts). Since version 1.6.0 Harbor is now a composite cloud-native registry which supports both container image management and Helm charts management. Access to Helm charts in Harbor is controlled by [role-based access controls (RBAC)](https://en.wikipedia.org/wiki/Role-based_access_control) and is restricted by projects.
 
-### Manage Helm Charts via portal
-#### List charts
+## Manage Helm Charts via the Harbor Interface
+### List charts
 Click your project to enter the project detail page after successful logging in. The existing helm charts will be listed under the tab `Helm Charts` which is beside the image `Repositories` tab with the following information:
 * Name of helm chart
 * The status of the chart: Active or Deprecated
 * The count of chart versions
 * The created time of the chart
 
-![list charts](../img/chartrepo/list_charts.png)
+![list charts](../img/list_charts.png)
 
 You can click the icon buttons on the top right to switch views between card view and list view.
 
-#### Upload new chart
+### Upload a New Chart
 Click the `UPLOAD` button on the top left to open the chart uploading dialog. Choose the uploading chart from your filesystem. Click the `UPLOAD` button to upload it to the chart repository server.
 
-![upload charts](../img/chartrepo/upload_charts.png)
+![upload charts](../img/upload_charts.png)
 
 If the chart is signed, you can choose the corresponding provenance file from your filesystem and Click the `UPLOAD` button to upload them together at once.
 
 If the chart is successfully uploaded, it will be displayed in the chart list at once.
 
-#### List chart versions
+### List Chart Versions
 Clicking the chart name from the chart list will show all the available versions of that chart with the following information:
 * the chart version number
 * the maintainers of the chart version
 * the template engine used (default is gotpl)
 * the created timestamp of the chart version
 
-![list charts versions](../img/chartrepo/list_chart_versions.png)
+![list charts versions](../img/list_chart_versions.png)
 
 Obviously, there will be at least 1 version for each of the charts in the top chart list. Same with chart list view, you can also click the icon buttons on the top right to switch views between card view and list view.
 
@@ -39,35 +38,35 @@ Check the checkbox at the 1st column to select the specified chart versions:
 * Click the `DOWNLOAD` button to download the chart artifact file. Batch operation is not supported.
 * Click the `UPLOAD` button to upload the new chart version for the current chart
 
-#### Adding labels to/remove labels from chart versions
-Users who have system administrator, project administrator or project developer role can click the `ADD LABELS` button to add labels to or remove labels from chart versions.
+### Adding Labels to and Removing Labels from Chart Versions
+Users who have Harbor system administrator, project administrator or project developer role can click the `ADD LABELS` button to add labels to or remove labels from chart versions.
 
-![add labels to chart versions](../img/chartrepo/add_labesl_to_chart_versions.png)
+![add labels to chart versions](../img/add_labesl_to_chart_versions.png)
 
 
-#### Filtering chart versions by labels
+### Filtering Chart Versions by Label
 The chart versions can be filtered by labels:
 
-![filter chart versions by labels](../img/chartrepo/filter_chart_versions_by_label.png)
+![filter chart versions by labels](../img/filter_chart_versions_by_label.png)
 
-#### View chart version details
+### View Chart Version Details
 Clicking the chart version number link will open the chart version details view. You can see more details about the specified chart version here. There are three content sections:
 * **Summary:**
   * readme of the chart
   * overall metadata like home, created timestamp and application version
   * related helm commands for reference, such as `helm add repo` and `helm install` etc.
-![chart details](../img/chartrepo/chart_details.png)
+![chart details](../img/chart_details.png)
 * **Dependencies:**
   * list all the dependant sun charts with 'name', 'version' and 'repository' fields
-![chart dependencies](../img/chartrepo/chart_dependencies.png)
+![chart dependencies](../img/chart_dependencies.png)
 * **Values:**
   * display the content from `values.yaml` file with highlight code preview
   * clicking the icon buttons on the top right to switch the yaml file view to k-v value pair list view
-![chart values](../img/chartrepo/chart_values.png)
+![chart values](../img/chart_values.png)
 
 Clicking the `DOWNLOAD` button on the top right will start the downloading process.
 
-### Working with Helm CLI
+## Working with the Helm CLI
 As a helm chart repository, Harbor can work smoothly with Helm CLI. About how to install Helm CLI, please refer [install helm](https://docs.helm.sh/using_helm/#installing-helm). Run command `helm version` to make sure the version of Helm CLI is v2.9.1+.
 ```
 helm version
@@ -75,7 +74,7 @@ helm version
 #Client: &version.Version{SemVer:"v2.9.1", GitCommit:"20adb27c7c5868466912eebdf6664e7390ebe710", GitTreeState:"clean"}
 #Server: &version.Version{SemVer:"v2.9.1", GitCommit:"20adb27c7c5868466912eebdf6664e7390ebe710", GitTreeState:"clean"}
 ```
-#### Add harbor to the repository list
+### Add Harbor to the Repository List
 Before working, Harbor should be added into the repository list with `helm repo add` command. Two different modes are supported.
 * Add Harbor as a unified single index entry point
 
@@ -92,7 +91,7 @@ With this mode, helm can only pull charts in the specified project.
 helm repo add --ca-file ca.crt --username=admin --password=Passw0rd myrepo https://xx.xx.xx.xx/chartrepo/myproject
 ```
 
-#### Push charts to the repository server by CLI
+### Push Charts to the Repository Server with the CLI
 As an alternative, you can also upload charts via the CLI. It is not supported by the native helm CLI. A plugin from the community should be installed before pushing. Run `helm plugin install` to install the `push` plugin first.
 ```
 helm plugin install https://github.com/chartmuseum/helm-push
@@ -103,7 +102,7 @@ helm push --ca-file=ca.crt --username=admin --password=passw0rd chart_repo/hello
 ```
 **NOTES:** `push` command does not support pushing a prov file of a signed chart yet.
 
-#### Install charts
+### Install Charts
 Before installing, make sure your helm is correctly initialized with command `helm init` and the chart index is synchronized with command `helm repo update`.
 
 Search the chart with the keyword if you're not sure where it is: