// Module included in the following assemblies:
//
// * installing/disconnected_install/installing-mirroring-installation-images.adoc
// * installing/disconnected_install/installing-mirroring-disconnected.adoc
// * openshift_images/samples-operator-alt-registry.adoc
// * scalability_and_performance/ztp_far_edge/ztp-deploying-far-edge-clusters-at-scale.adoc
// * updating/updating_a_cluster/updating_disconnected_cluster/mirroring-image-repository.adoc

ifeval::["{context}" == "mirroring-ocp-image-repository"]
:restricted:
:update-oc-mirror:
endif::[]

ifeval::["{context}" == "installing-mirroring-installation-images"]
:restricted:
endif::[]

ifeval::["{context}" == "installing-mirroring-disconnected"]
:restricted:
:oc-mirror:
endif::[]

ifeval::["{context}" == "about-installing-oc-mirror-v2"]
:oc-mirror-v2:
:restricted:
endif::[]

:_mod-docs-content-type: PROCEDURE
[id="installation-adding-registry-pull-secret_{context}"]
= Configuring credentials that allow images to be mirrored

[role="_abstract"]
Create a container image registry credentials file so that you can mirror images from Red{nbsp}Hat to your mirror. Complete the following steps on the installation host.

ifdef::restricted[]
[WARNING]
====
Do not use this image registry credentials file as the pull secret when you install a cluster. If you provide this file when you install cluster, all of the machines in the cluster will have write access to your mirror registry.
====
endif::restricted[]

// removed this warning since the first part is more of a prereq, and the second part seems to just describe what will happen later in the procedure. Can revert/modify as needed.

.Prerequisites
ifndef::openshift-rosa,openshift-dedicated[]
* You configured a mirror registry to use in your disconnected environment.
endif::openshift-rosa,openshift-dedicated[]
ifdef::openshift-rosa,openshift-dedicated[]
* You configured a mirror registry to use.
endif::openshift-rosa,openshift-dedicated[]
ifdef::restricted[]
* You identified an image repository location on your mirror registry to mirror images into.
* You provisioned a mirror registry account that allows images to be uploaded to that image repository.
* You have write access to the mirror registry.
endif::restricted[]

.Procedure
ifndef::openshift-origin[]
. Download your `registry.redhat.io` {cluster-manager-url-pull}.

. Make a copy of your pull secret in JSON format by running the following command:
+
[source,terminal]
----
$ cat ./pull-secret | jq . > <path>/<pull_secret_file_in_json>
----
+
Specify the path to the directory to store the pull secret in and a name for the JSON file that you create.
+
.Example pull secret
[source,json]
----
{
  "auths": {
    "cloud.openshift.com": {
      "auth": "b3BlbnNo...",
      "email": "you@example.com"
    },
    "quay.io": {
      "auth": "b3BlbnNo...",
      "email": "you@example.com"
    },
    "registry.connect.redhat.com": {
      "auth": "NTE3Njg5Nj...",
      "email": "you@example.com"
    },
    "registry.redhat.io": {
      "auth": "NTE3Njg5Nj...",
      "email": "you@example.com"
    }
  }
}
----
+
ifdef::oc-mirror[]
. Save the file as either `~/.docker/config.json` or `$XDG_RUNTIME_DIR/containers/auth.json`:
+
// An additional step for following this procedure when using oc-mirror as part of the disconnected install process.

.. If the `.docker` or `$XDG_RUNTIME_DIR/containers` directories do not exist, create one by entering the following command:
+
[source,terminal]
----
$ mkdir -p <directory_name>
----
+
Where `<directory_name>` is either `~/.docker` or `$XDG_RUNTIME_DIR/containers`.

.. Copy the pull secret to the appropriate directory by entering the following command:
+
[source,terminal]
----
$ cp <path>/<pull_secret_file_in_json> <directory_name>/<auth_file>
----
+
The `<directory_name>` is either `~/.docker` or `$XDG_RUNTIME_DIR/containers`, and `<auth_file>` is either `config.json` or `auth.json`
endif::oc-mirror[]
ifdef::update-oc-mirror[]

. Optional: If using the oc-mirror plugin, save the file as either `~/.docker/config.json` or `$XDG_RUNTIME_DIR/containers/auth.json`:
+
// Similar to the additional step above, except it is framed as optional because it is included in a disconnected update page (where users may or may not use oc-mirror for their process)
	
** If the `.docker` or `$XDG_RUNTIME_DIR/containers` directories do not exist, create one by entering the following command:
+
[source,terminal]
----
$ mkdir -p <directory_name>
----
+
Where `<directory_name>` is either `~/.docker` or `$XDG_RUNTIME_DIR/containers`.

** Copy the pull secret to the appropriate directory by entering the following command:
+
[source,terminal]
----
$ cp <path>/<pull_secret_file_in_json> <directory_name>/<auth_file>
----
+
Where `<directory_name>` is either `~/.docker` or `$XDG_RUNTIME_DIR/containers`, and `<auth_file>` is either `config.json` or `auth.json`.

endif::update-oc-mirror[]
ifdef::oc-mirror-v2[]

. If the `$XDG_RUNTIME_DIR/containers` directory does not exist, create one by entering the following command:
+
[source,terminal]
----
$ mkdir -p $XDG_RUNTIME_DIR/containers
----
+
// Additional step for allowing this procedure for oc-mirror-v2
+
// Should this step below also have the "if you don't have this directory, create it using this command" substeps?

. Save the pull secret file as `$XDG_RUNTIME_DIR/containers/auth.json`.
endif::oc-mirror-v2[]
endif::openshift-origin[]

. Generate the base64-encoded user name and password or token for your mirror registry by running the following command:
+
[source,terminal]
----
$ echo -n '<user_name>:<password>' | base64 -w0
----
For `<user_name>` and `<password>`, specify the user name and password that you configured for your registry.
+
.Example output
[source,terminal]
----
BGVtbYk3ZHAtqXs=
----

ifdef::openshift-origin[]
. Create a `.json` file and add a section that describes your registry to it:
+
[source,json]
----
{
  "auths": {
    "<mirror_registry>": {
      "auth": "<credentials>",
      "email": "you@example.com"
    }
  }
}
----
+
* For the `<mirror_registry>` value, specify the registry domain name, and optionally the port, that your mirror registry uses to serve content. For example, `registry.example.com` or `registry.example.com:8443`.
+
* For the `<credentials>` value, specify the base64-encoded user name and password for the mirror registry.

endif::openshift-origin[]

ifndef::openshift-origin[]
. Edit the JSON file and add a section that describes your registry to it:
+
[source,json]
----
  "auths": {
    "<mirror_registry>": {
      "auth": "<credentials>",
      "email": "you@example.com"
    }
  },
----
+
* For the `<mirror_registry>` value, specify the registry domain name, and optionally the port, that your mirror registry uses to serve content. For example, `registry.example.com` or `registry.example.com:8443`.
+
* For the `<credentials>` value, specify the base64-encoded user name and password for the mirror registry.
+
.Example modified pull secret
[source,json]
----
{
  "auths": {
    "registry.example.com": {
      "auth": "BGVtbYk3ZHAtqXs=",
      "email": "you@example.com"
    },
    "cloud.openshift.com": {
      "auth": "b3BlbnNo...",
      "email": "you@example.com"
    },
    "quay.io": {
      "auth": "b3BlbnNo...",
      "email": "you@example.com"
    },
    "registry.connect.redhat.com": {
      "auth": "NTE3Njg5Nj...",
      "email": "you@example.com"
    },
    "registry.redhat.io": {
      "auth": "NTE3Njg5Nj...",
      "email": "you@example.com"
    }
  }
}
----
endif::openshift-origin[]

////
This is not currently working as intended.
. Log in to your registry by using the following command:
+
[source,terminal]
----
$ oc registry login --to ./pull-secret.json --registry "<registry_host_and_port>" --auth-basic=<username>:<password>
----
+
Provide both the registry details and a valid user name and password for the registry.
////

ifeval::["{context}" == "installing-mirroring-installation-images"]
:!restricted:
endif::[]

ifeval::["{context}" == "mirroring-ocp-image-repository"]
:!restricted:
:!update-oc-mirror:
endif::[]

ifeval::["{context}" == "installing-mirroring-disconnected"]
:!restricted:
:!oc-mirror:
endif::[]

ifeval::["{context}" == "about-installing-oc-mirror-v2"]
:!oc-mirror-v2:
:!restricted:
endif::[]

