(Update) Rework ImageRepo (#11588)

* (Update) Rework ImageRepo

Added clarifications for Image repo, and also consistent documentation for when image info is necessary. to reduce confusion.
Added Shared documentation.

* quote change

* Consistency edits

* Resolve URLS properly

* Update docs/continuous-integration/shared/imageregistry-whenreq.md

Co-authored-by: SushrutHarness <[email protected]>

---------

Co-authored-by: SushrutHarness <[email protected]>

Author: KinnonYee-harness

docs/continuous-integration/shared/imageregistry-imagesfqn.md

@@ -0,0 +1,44 @@
+#### What are the expected values for Container Registry and Image
+
+For **Container Registry** settings, provide a Harness container registry connector, such as a [Docker connector](/docs/platform/connectors/cloud-providers/ref-cloud-providers/docker-registry-connector-settings-reference/), that connects to a container registry, such as Docker Hub, where the **Image** is located.
+
+For **Image**, provide the FQN (fully-qualified name) or artifact name and tag of the Docker image to use when this step runs commands, for example `us-docker.pkg.dev/gar-prod-setup/harness-public/harness/cache:latest` or `maven:3.8-jdk-11`. If you don't include a tag, Harness uses the `latest` tag.   Depending on the connector and feature flags set, **an FQN may be required**.
+
+You can use any Docker image from any Docker registry, including Docker images from private registries. Different container registries require different name formats, for example:
+
+* **Docker Registry:** Input the name of the artifact you want to deploy, such as `library/tomcat`. Wildcards aren't supported. FQN is required for images in private container registries.
+* **ECR:** Input the FQN of the artifact you want to deploy. Images in repos must reference a path, for example: `40000005317.dkr.ecr.us-east-1.amazonaws.com/todolist:0.2`.
+* **GAR:** Input the FQN of the artifact you want to deploy. Images in repos must reference a path starting with the project ID that the artifact is in, for example: `us-docker.pkg.dev/gar-prod-setup/harness-public/harness/cache:latest`.
+
+    ![](./static/run-step-settings-03.png)
+    <figcaption>Configuring a Container Registry and Image settings.</figcaption>
+
+:::note Remove FQN Requirement
+Customers who want to utilize non-FQN references for non public Docker-registry connectors will need to contact Harness Support to add the feature flags, `CI_REMOVE_FQN_DEPENDENCY_FOR_PRIVATE_REGISTRY_CONNECTOR_DOCKER` and `CI_REMOVE_FQN_DEPENDENCY`.
+:::
+
+#### Pulling images from JFrog Artifactory Docker registries
+
+If you need to pull images from a JFrog Artifactory Docker registry, create a Docker connector that connects to your JFrog instance. **Don't use the Harness Artifactory connector** - The Artifactory connector only supports JFrog non-Docker registries.
+
+To create a Docker connector for a JFrog Docker registry:
+
+1. Go to **Connectors** in your Harness project, organization, or account resources, and select **New Connector**.
+2. Select **Docker Registry** under **Artifact Repositories**.
+3. Enter a **Name** for the connector. The **Description** and **Tags** are optional.
+4. For **Provider Type**, Select **Other**.
+5. In **Docker Registry URL**, enter your JFrog URL, such as `https://mycompany.jfrog.io`.
+6. In the **Authentication** settings, you must use **Username and Password** authentication.
+   * **Username:** Enter your JFrog username.
+   * **Password:** Select or create a [Harness text secret](/docs/platform/secrets/add-use-text-secrets) containing the password corresponding with the **Username**.
+7. Complete any other settings and save the connector. For information all Docker Registry connector settings, go to the [Docker connector settings reference](/docs/platform/connectors/cloud-providers/ref-cloud-providers/docker-registry-connector-settings-reference).
+
+
+One completed, please remember to use the FQN location of the image unless you have set the [appropriate feature flags as listed above](#what-are-the-expected-values-for-container-registry-and-image)
+
+:::tip JFrog URLs
+The JFrog URL format depends on your Artifactory configuration, and whether your Artifactory instance is local, virtual, remote, or behind a proxy. To get your JFrog URL, you can select your repo in your JFrog instance, select **Set Me Up**, and get the repository URL from the server name in the `docker-login` command.
+![](./static/artifactory-connector-settings-reference-09.png)
+
+For more information, go to the JFrog documentation on [Repository Management](https://www.jfrog.com/confluence/display/JFROG/Repository+Management) and [Configuring Docker Repositories](https://www.jfrog.com/confluence/display/RTF/Docker+Registry#DockerRegistry-ConfiguringDockerRepositories).
+:::

docs/continuous-integration/shared/imageregistry-whenreq.md

@@ -0,0 +1,8 @@
+#### When are Container Registry and Image required?
+
+The stage's build infrastructure determines whether these fields are required or optional:
+
+* [Kubernetes cluster build infrastructure](/docs/continuous-integration/use-ci/set-up-build-infrastructure/k8s-build-infrastructure/set-up-a-kubernetes-cluster-build-infrastructure.md): **Container Registry** and **Image** are always required.
+* [Local runner build infrastructure](/docs/continuous-integration/use-ci/set-up-build-infrastructure/define-a-docker-build-infrastructure.md): **Run Tests** steps can use binaries available on the host machine. The **Container Registry** and **Image** are required if the machine doesn't have the binaries you need.
+* [Self-managed AWS/GCP/Azure VM build infrastructure](/docs/category/set-up-vm-build-infrastructures): **Run Tests** steps can use binaries that you've made available on your build VMs. The **Container Registry** and **Image** are required if the VM doesn't have the necessary binaries. These fields are located under **Additional Configuration** for stages that use self-managed VM build infrastructure.
+* [Harness Cloud build infrastructure](/docs/continuous-integration/use-ci/set-up-build-infrastructure/use-harness-cloud-build-infrastructure.md): **Run Tests** steps can use binaries available on Harness Cloud machines, as described in the [image specifications](/docs/continuous-integration/use-ci/set-up-build-infrastructure/use-harness-cloud-build-infrastructure#platforms-and-image-specifications). The **Container Registry** and **Image** are required if the machine doesn't have the binaries you need. These fields are located under **Additional Configuration** for stages that use Harness Cloud build infrastructure.

docs/continuous-integration/shared/static/artifactory-connector-settings-reference-09.png

@@ -10,6 +10,8 @@ redirect_from:
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
+import WhenReq from '/docs/continuous-integration/shared/imageregistry-whenreq.md';
+import FQNImage from '/docs/continuous-integration/shared/imageregistry-imagesfqn.md';
 
 If your pipelines use [webhook triggers](/docs/platform/triggers/triggering-pipelines), you can get [Harness build statuses in your PRs](#pipeline-links-in-prs). However, you must configure your protection rules *in your SCM provider* if you want failed/running builds to block PR merges.
 
@@ -52,10 +54,10 @@ These steps explain how to add a status check that uses the GitHub API. For info
 2. Create [GitHub Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) to use for authentication, and save the token as a [Harness text secret](/docs/platform/secrets/add-use-text-secrets).
 3. Add a [Run step](../run-step-settings.md) to your **Build** (`CI`) stage.
 4. Enter a **Name** for the step.
-5. If required by your build infrastructure, provide the **Container Registry** and **Image**.
+5. If required by your build infrastructure, provide the **Container Registry** and **Image**.  For more information on how to set this up, please [look at the section below about Container Registry and Image](#container-registry-and-image)
    * **Container Registry** is a container registry connector, such as a Docker connector.
    * **Image** is the FQN or artifact name and tag of a Docker image that has cURL installed, such as `curlimages/curl:latest` for the [official cURL Docker Hub image](https://hub.docker.com/r/curlimages/curl).
-   * To learn more about this setting and when it is required, go to [Use Run steps - Container Registry and Image](../run-step-settings.md#container-registry-and-image).
+   * To learn more about this setting and when it is required, [look at the section below about Container Registry and Image](#container-registry-and-image)
 6. For **Shell**, select **Sh**.
 7. In **Command**, enter a script that calls the GitHub API, for example:
 
@@ -167,6 +169,14 @@ You can package your status check script in a [custom plugin](../use-drone-plugi
 </TabItem>
 </Tabs>
 
+### Container Registry and Image
+
+The build environment must have the necessary binaries for the **SCM Status Checks**. Depending on the stage's build infrastructure, **SCM Status Checks** steps can use binaries that exist in the build environment, or use **Container Registry** and **Image** to pull an image, such as a public or private Docker image, that contains the required binaries. 
+
+<WhenReq />
+
+<FQNImage />
+
 ## Troubleshoot status checks
 
 Go to the [Harness CI Knowledge Base](/kb/continuous-integration/continuous-integration-faqs) for common questions and issues related to codebases and SCM status checks, such as:

docs/continuous-integration/shared/static/run-step-settings-03.png

@@ -13,7 +13,8 @@ redirect_from:
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
-
+import WhenReq from '/docs/continuous-integration/shared/imageregistry-whenreq.md';
+import FQNImage from '/docs/continuous-integration/shared/imageregistry-imagesfqn.md';
 
 Use Background steps to [manage dependent services](./dependency-mgmt-strategies.md) that need to run for the entire lifetime of a Build stage. For example, you can set up your pipeline to run multiple background services that implement a local, multi-service app.
 
@@ -57,13 +58,11 @@ If the Background step runs directly on the host or in a Kubernetes cluster buil
 
 ## Container Registry and Image
 
-**Container Registry** is a Harness container registry connector that connects to the container registry, such as Docker Hub, from which you want Harness to pull an image.
+The build environment must have the necessary binaries for the **Background** step to execute your test commands. Depending on the stage's build infrastructure, **Background** steps can use binaries that exist in the build environment, or use **Container Registry** and **Image** to pull an image, such as a public or private Docker image, that contains the required binaries. 
 
-**Image** is the container image to use for the background service. The image name should include the tag, or it defaults to the `latest` tag if unspecified. You can use any Docker image from any Docker registry, including Docker images from private registries. Different container registries require different name formats:
+<WhenReq />
 
-* **Docker Registry:** Input the name of the artifact you want to deploy, such as `library/tomcat`. Wildcards aren't supported. FQN is required for images in private container registries.
-* **ECR:** Input the FQN (fully-qualified name) of the artifact you want to deploy. Images in repos must reference a path, for example: `40000005317.dkr.ecr.us-east-1.amazonaws.com/todolist:0.2`.
-* **GAR:** Input the FQN (fully-qualified name) of the artifact you want to deploy. Images in repos must reference a path starting with the project ID that the artifact is in, for example: `us-docker.pkg.dev/gar-prod-setup/harness-public/harness/cache:latest`.
+<FQNImage />
 
 <figure>
 

docs/continuous-integration/use-ci/codebase-configuration/scm-status-checks.md

@@ -13,6 +13,8 @@ canonical_url: https://www.harness.io/blog/docker-multi-stage-build
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
+import WhenReq from '/docs/continuous-integration/shared/imageregistry-whenreq.md';
+import FQNImage from '/docs/continuous-integration/shared/imageregistry-imagesfqn.md';
 
 CI pipelines that use a [Kubernetes cluster build infrastructure](/docs/category/set-up-kubernetes-cluster-build-infrastructures) need Docker-in-Docker (DinD) if you need to run Docker commands as part of the build process. For example, if you want to build images from [two separate codebases in the same pipeline](/docs/continuous-integration/use-ci/codebase-configuration/clone-and-process-multiple-codebases-in-the-same-pipeline.md): One with a [Build and Push to Docker step](/docs/continuous-integration/use-ci/build-and-upload-artifacts/build-and-push/build-and-push-to-docker-registry.md) and another with Docker commands in a [Run step](/docs/continuous-integration/use-ci/run-step-settings.md).
 
@@ -57,8 +59,8 @@ To demonstrate how to set up DinD in Harness CI, this topic creates a pipeline t
 In your **Build** stage, select the **Execution** tab, and add a [Background step](./background-step-settings.md) configured as follows:
 
 1. For **Name**, enter `dind_Service`.
-2. For **Container Registry**, select your [Docker connector](/docs/platform/connectors/cloud-providers/ref-cloud-providers/docker-registry-connector-settings-reference).
-3. For **Image**, enter the name and tag for the image that you want to use to run DinD, such as [docker:dind](https://hub.docker.com/_/docker).
+2. For **Container Registry**, select your [Docker connector](/docs/platform/connectors/cloud-providers/ref-cloud-providers/docker-registry-connector-settings-reference). 
+3. For **Image**, enter the name and tag for the image that you want to use to run DinD, such as [docker:dind](https://hub.docker.com/_/docker).  In some cases, an FQN may be necessary. More information can be found below [about setting up the registry and image](#container-registry-and-image).
 4. Under **Additional Configuration**, select **Privileged**. [Privileged mode is required](#privileged-mode-required) Docker-in-Docker to run correctly.
 5. In **Entry Point**, you can provide a list of arguments, if needed. For example, the entry point for the `docker:dind` image is `docker-entrypoint.sh`. If you want to add a `--mtu` argument, you would include both the image entry point and the additional argument in the **Entry Point** specification.
 
@@ -87,7 +89,7 @@ After the **Background** step, add a **Run** step to run your Docker commands. C
 
 1. Enter a **Name**.
 2. For **Container Registry**, select your [Docker connector](/docs/platform/connectors/cloud-providers/ref-cloud-providers/docker-registry-connector-settings-reference).
-3. For **Image**, enter the name and tag for the Docker image, with the Docker binary, that you want to use to execute the content of **Command**.
+3. For **Image**, enter the name and tag for the Docker image, with the Docker binary, that you want to use to execute the content of **Command**.  In some cases, an FQN may be necessary. More information can be found below [about setting up the registry and image](#container-registry-and-image).
 4. In **Command**, enter the shell commands you want to run in this step.
 
    For example, the following commands clone a Git repo, build an image, and push the image to a Docker registry:
@@ -132,6 +134,15 @@ You can also add steps to your pipeline that [run health checks on background se
 
 When you run your pipeline, you can review the step logs on the [Build details page](../viewing-builds.md).
 
+### Container Registry and Image
+
+The build environment must have the necessary binaries for the **DinD** step. Depending on the stage's build infrastructure, **DinD** steps can use binaries that exist in the build environment, or use **Container Registry** and **Image** to pull an image, such as a public or private Docker image, that contains the required binaries.
+
+<WhenReq />
+
+<FQNImage />
+
+
 ## Pipeline YAML example
 
 The following YAML example defines a pipeline that:

docs/continuous-integration/use-ci/manage-dependencies/background-step-settings.md

@@ -16,6 +16,7 @@ import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import EnhancedOutVar from '/docs/continuous-integration/shared/enhanced-output-variables.md';
 import OutVar from '/docs/continuous-integration/shared/output-var.md';
+import FQNImage from '/docs/continuous-integration/shared/imageregistry-imagesfqn.md';
 
 You can use a **Run** step to run commands or scripts in a CI pipeline. Here are some examples of different ways you can use **Run** steps.
 
@@ -251,56 +252,7 @@ The stage's build infrastructure determines whether these fields are required or
 
 </details>
 
-<details>
-<summary>What are the expected values for Container Registry and Image?</summary>
-
-For **Container Registry**, provide a Harness container registry connector, such as a [Docker connector](/docs/platform/connectors/cloud-providers/ref-cloud-providers/docker-registry-connector-settings-reference/), that connects to a container registry, such as Docker Hub, where the **Image** is located.
-
-For **Image**, provide the FQN (fully-qualified name) or artifact name and tag of the Docker image to use when this step runs commands, for example `us-docker.pkg.dev/gar-prod-setup/harness-public/harness/cache:latest` or `maven:3.8-jdk-11`. If you don't include a tag, Harness uses the `latest` tag.
-
-You can use any Docker image from any Docker registry, including Docker images from private registries. Different container registries require different name formats, for example:
-
-* **Docker Registry:** Input the name of the artifact you want to deploy, such as `library/tomcat`. Wildcards aren't supported. FQN is required for images in private container registries.
-* **ECR:** Input the FQN of the artifact you want to deploy. Images in repos must reference a path, for example: `40000005317.dkr.ecr.us-east-1.amazonaws.com/todolist:0.2`.
-* **GAR:** Input the FQN of the artifact you want to deploy. Images in repos must reference a path starting with the project ID that the artifact is in, for example: `us-docker.pkg.dev/gar-prod-setup/harness-public/harness/cache:latest`.
-
-<figure>
-
-![](./static/run-step-settings-03.png)
-
-<figcaption>Configuring a Container Registry and Image settings.</figcaption>
-</figure>
-
-</details>
-
-<details>
-<summary>Pulling images from JFrog Artifactory Docker registries</summary>
-
-If you need to pull images from a JFrog Artifactory Docker registry, create a Docker connector that connects to your JFrog instance. **Don't use the Harness Artifactory connector** - The Artifactory connector only supports JFrog non-Docker registries.
-
-To create a Docker connector for a JFrog Docker registry:
-
-1. Go to **Connectors** in your Harness project, organization, or account resources, and select **New Connector**.
-2. Select **Docker Registry** under **Artifact Repositories**.
-3. Enter a **Name** for the connector. The **Description** and **Tags** are optional.
-4. For **Provider Type**, Select **Other**.
-5. In **Docker Registry URL**, enter your JFrog URL, such as `https://mycompany.jfrog.io`.
-6. In the **Authentication** settings, you must use **Username and Password** authentication.
-   * **Username:** Enter your JFrog username.
-   * **Password:** Select or create a [Harness text secret](/docs/platform/secrets/add-use-text-secrets) containing the password corresponding with the **Username**.
-7. Complete any other settings and save the connector. For information all Docker Registry connector settings, go to the [Docker connector settings reference](/docs/platform/connectors/cloud-providers/ref-cloud-providers/docker-registry-connector-settings-reference).
-
-:::tip JFrog URLs
-
-The JFrog URL format depends on your Artifactory configuration, and whether your Artifactory instance is local, virtual, remote, or behind a proxy. To get your JFrog URL, you can select your repo in your JFrog instance, select **Set Me Up**, and get the repository URL from the server name in the `docker-login` command.
-
-![](./static/artifactory-connector-settings-reference-09.png)
-
-For more information, go to the JFrog documentation on [Repository Management](https://www.jfrog.com/confluence/display/JFROG/Repository+Management) and [Configuring Docker Repositories](https://www.jfrog.com/confluence/display/RTF/Docker+Registry#DockerRegistry-ConfiguringDockerRepositories).
-
-:::
-
-</details>
+<FQNImage />
 
 ### Shell and Command