diff --git a/.asciidoctorconfig b/.asciidoctorconfig new file mode 100644 index 0000000..cf74c38 --- /dev/null +++ b/.asciidoctorconfig @@ -0,0 +1,10 @@ +// .asciidoctorconfig +// Specifies Asciidoctor configuration to preview files in the editor +// See: https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features/advanced/asciidoctorconfig-file.html + +:docinfo: shared +:docinfodir: {asciidoctorconfigdir}/.asciidoctor +:toc: +:linkcss: +:stylesdir: https://crc.dev/docs/_/css/ +:stylesheet: site.css diff --git a/antora-playbook.yml b/antora-playbook.yml index ddd852d..4bdac43 100644 --- a/antora-playbook.yml +++ b/antora-playbook.yml @@ -1,7 +1,7 @@ --- site: title: CRC Documentation - start_page: getting_started:getting_started:introducing.adoc + start_page: ROOT::introducing.adoc url: https://crc.dev/docs robots: allow content: @@ -55,10 +55,8 @@ asciidoc: bin: crc # Documentation naming context: crc - crc-gsg: CRC Getting Started Guide # URLs crc-download-url: https://console.redhat.com/openshift/create/local - crc-gsg-url: https://crc.dev/crc/ openshift-installer-url: https://console.redhat.com/openshift/create openshift-docs-url: https://docs.openshift.com/container-platform/latest openshift-docs-url-landing-page: "{openshift-docs-url}/welcome/index.html#developer-activities" diff --git a/antora.yml b/antora.yml index 47163df..4048bf2 100644 --- a/antora.yml +++ b/antora.yml @@ -1,7 +1,7 @@ --- -name: getting_started +name: ROOT # Publish without subdirectory title: Getting started with CRC version: ~ # Unversioned component version -start_page: getting_started:introducing.adoc +start_page: introducing.adoc nav: - - modules/getting_started/nav.adoc + - modules/ROOT/nav.adoc diff --git a/modules/getting_started/nav.adoc b/modules/ROOT/nav.adoc similarity index 100% rename from modules/getting_started/nav.adoc rename to modules/ROOT/nav.adoc diff --git a/modules/ROOT/pages/administrative-tasks.adoc b/modules/ROOT/pages/administrative-tasks.adoc new file mode 100644 index 0000000..a3f9965 --- /dev/null +++ b/modules/ROOT/pages/administrative-tasks.adoc @@ -0,0 +1,70 @@ +:description: Administrative tasks += Administrative tasks + +== Starting monitoring + +{prod} disables cluster monitoring by default to ensure that {prod} can run on a typical notebook. +Monitoring is responsible for listing your cluster in the link:https://console.redhat.com/openshift[Red Hat Hybrid Cloud Console]. +Follow this procedure to enable monitoring for your cluster. + +.Prerequisites +* You must assign additional memory to the {prod} instance. +At least 14 GiB of memory, a value of `14336`, is recommended for core functionality. +Increased workloads will require more memory. +For more information, see xref:configuring.adoc#configuring-the-instance[Configuring the instance]. + +.Procedure +. Set the `enable-cluster-monitoring` configurable property to `true`: ++ +[subs="+quotes,attributes"] +---- +$ {bin} config set enable-cluster-monitoring true +---- + +. Start the instance: ++ +[subs="+quotes,attributes"] +---- +$ {bin} start +---- ++ +[WARNING] +==== +Cluster monitoring cannot be disabled. +To remove monitoring, set the `enable-cluster-monitoring` configurable property to `false` and delete the existing {prod} instance. +==== + +== Enabling override Operators + +To verify {prod} can run on a typical notebook, some resource-heavy services get disabled by default. +These services can be enabled by manually removing the desired Operator from the Operator override list. + +.Prerequisites +* A running {prod} virtual machine and a working [command]`oc` command. +For more information, see xref:using.adoc#accessing-the-openshift-cluster-with-the-openshift-cli[Accessing the OpenShift cluster with `oc`]. +* You must log in through [command]`oc` as the `kubeadmin` user. + +.Procedure +. List unmanaged Operators and note the numeric index for the desired Operator: + +** On Linux or {mac}: ++ +[subs="+quotes"] +---- +$ oc get clusterversion version -ojsonpath='{range .spec.overrides[*]}{.name}{"\n"}{end}' | nl -v -2 +---- + +** On {msw} using PowerShell: ++ +[subs="+quotes"] +---- +PS> oc get clusterversion version -ojsonpath='{range .spec.overrides[*]}{.name}{"\n"}{end}' | % {$nl++;"`t$($nl-3) `t $_"};$nl=0 +---- + +. Start the desired Operator using the identified numeric index: ++ +[subs="+quotes"] +---- +$ oc patch clusterversion/version --type='json' -p '[{"op":"remove", "path":"/spec/overrides/__"}]' +clusterversion.config.openshift.io/version patched +---- diff --git a/modules/ROOT/pages/configuring.adoc b/modules/ROOT/pages/configuring.adoc new file mode 100644 index 0000000..4d1c212 --- /dev/null +++ b/modules/ROOT/pages/configuring.adoc @@ -0,0 +1,138 @@ +:description: Configuring {prod} += Configuring {prod} + +[id='about-configuration'] +== About {prod} configuration + +Use the [command]`{bin} config` command to configure both the [command]`{bin}` executable and the {prod} instance. +The [command]`{bin} config` command requires a subcommand to act on the configuration. +The available subcommands are `get`, `set,` `unset`, and `view`. +The `get`, `set`, and `unset` subcommands operate on named configurable properties. +Run the [command]`{bin} config --help` command to list the available properties. + +You can also use the [command]`{bin} config` command to configure the behavior of the startup checks for the [command]`{bin} start` and [command]`{bin} setup` commands. +By default, startup checks report an error and stop execution when their conditions are not met. +Set the value of a property starting with `skip-check` to `true` to skip the check. + +[id='viewing-configuration'] +== Viewing {prod} configuration + +The {prod} executable provides commands to view configurable properties and the current {prod} configuration. + +.Procedure +. To view the complete current configuration diverting from default values: ++ +[subs="+quotes,attributes"] +---- +$ {bin} config view +---- + +. To list the available configurable properties: ++ +[subs="+quotes,attributes"] +---- +$ {bin} config --help +---- + +. To view the values for a configurable property: ++ +[subs="+quotes,attributes"] +---- +$ {bin} config get __ +---- + +[id='changing-the-selected-preset'] +== Changing the selected preset + +You can change the container runtime used for the {prod} instance by selecting the desired preset before creating the instance. + +You cannot change the preset of an existing {prod} instance. + +.Procedure +. Change the selected preset from the command line: ++ +[subs="+quotes,attributes"] +---- +$ {bin} config set preset ____ +---- ++ +Valid preset names are: ++ +.Preset names +[%header,format=csv,cols="1,2"] +|=== +Name, Preset +`openshift`, {ocp} +`okd`, {okd} +`microshift`, {ushift} +|=== + +. Save any desired information stored in your existing instance. + +. Delete the existing {prod} instance. ++ +[subs="+quotes,attributes"] +---- +$ {bin} delete +---- + +. Start the new {prod} instance: ++ +[subs="+quotes,attributes"] +---- +$ {bin} start +---- + +[id='configuring-the-instance'] +== Configuring the instance + +Use the `cpus` and `memory` properties to configure the default number of vCPUs and amount of memory available to the {prod} instance, respectively. + +Alternatively, the number of vCPUs and amount of memory can be assigned using the `--cpus` and `--memory` flags to the `{bin} start` command, respectively. + +[IMPORTANT] +==== +You cannot change the configuration of a running {prod} instance. +To enable configuration changes, you must stop the running instance and start it again. +==== + +.Procedure +. To configure the number of vCPUs available to the instance: ++ +[subs="+quotes,attributes"] +---- +$ {bin} config set cpus ____ +---- ++ +The default value for the `cpus` property is `4`. +The number of vCPUs to assign must be greater than or equal to the default. + +. To start the instance with the desired number of vCPUs: ++ +[subs="+quotes,attributes"] +---- +$ {bin} start --cpus ____ +---- + +. To configure the memory available to the instance: ++ +[subs="+quotes,attributes"] +---- +$ {bin} config set memory ____ +---- ++ +[NOTE] +==== +Values for available memory are set in mebibytes (MiB). +One gibibyte (GiB) of memory is equal to 1024 MiB. +==== ++ +The default value for the `memory` property is `10752`. +The amount of memory to assign must be greater than or equal to the default. + +. To start the instance with the desired amount of memory: ++ +[subs="+quotes,attributes"] +---- +$ {bin} start --memory ____ +---- diff --git a/modules/ROOT/pages/installing.adoc b/modules/ROOT/pages/installing.adoc new file mode 100644 index 0000000..70e6e07 --- /dev/null +++ b/modules/ROOT/pages/installing.adoc @@ -0,0 +1,230 @@ +:description: Installing {prod} += Installing {prod} + +[id='minimum-system-requirements'] +== Minimum system requirements + +[role="_abstract"] +{prod} has the following minimum hardware and operating system requirements. + +=== Hardware requirements + +{prod} is supported on these architectures: + +.Preset and architecture compatibility +[%header,format=csv,cols="2,1,1,1"] +|=== +Preset, AMD63, Intel 64, Apple silicon +{ocp}, yes, yes, yes +{okd}, yes, yes, no +{ushift}, yes, yes, yes +|=== + +{prod} does not support nested virtualization. + +Depending on the desired container runtime, {prod} requires the following system resources: + +==== For {ocp} + +* 4 physical CPU cores +* 10.5 GB of free memory +* 35 GB of storage space + +==== For {ushift} + +* 2 physical CPU cores +* 4 GB of free memory +* 35 GB of storage space + +[NOTE] +==== +The {ocp} and {ushift} presets require these minimum resources to run in the {prod} instance. +Some workloads might require more resources. +To assign more resources to the {prod} instance, see xref:configuring.adoc[Configuring the instance]. +==== + +=== Operating system requirements + +{prod} requires the following minimum version of a supported operating system: + +{msw}:: + +* Fully updated {msw} 10 or {msw} 11. +* {prod} does not work on earlier {msw} versions. +* {prod} does not work on {msw} Home Edition. + +{mac}:: + +* {mac} 13 Ventura or later. +* {prod} does not work on earlier {mac} versions. + +Linux:: + +{rhel}::: +* Latest two minor releases. +* The host running {prod} is link:https://access.redhat.com/solutions/253273[registered with the Red Hat Customer Portal]. +* `libvirt` and `NetworkManager` packages are installed. ++ +---- +sudo dnf install libvirt NetworkManager +---- + +{centos}::: +* Latest two 8 and 9 minor releases. +* `libvirt` and `NetworkManager` packages are installed. ++ +---- +sudo dnf install libvirt NetworkManager +---- + +{fed}::: +* Latest two stable releases. +* `libvirt` and `NetworkManager` packages are installed. ++ +---- +sudo dnf install libvirt NetworkManager +---- + +{ubuntu} 18.04 LTS or later and {debian} 10 or later::: +* Not supported. +* Might require manual set up of the host machine. +* `libvirt` and `network-manager` packages are installed. ++ +---- +sudo apt install qemu-kvm libvirt-daemon libvirt-daemon-system network-manager +---- + +[id='installing'] +== Installing {prod} + +{prod} is available as a portable executable for {rhel}. +On {msw} and {mac}, {prod} is available using a guided installer. + +.Prerequisites +* Your host machine meets the xref:minimum-system-requirements[minimum system requirements]. + +.Procedure +. Download the link:{crc-download-url}[latest release of {prod}] for your platform. + +. On {msw}, extract the contents of the archive. + +. On {mac} or {msw}, run the guided installer and follow the instructions. ++ +[NOTE] +==== +On {msw}, you must install {prod} to your local [filename]*_C:\_* drive. +You cannot run {prod} from a network drive. +==== ++ +On {rhel}, assuming the archive is in the [filename]*_~/Downloads_* directory, follow these steps: ++ +.. Extract the contents of the archive: ++ +[subs="attributes"] +---- +$ cd ~/Downloads +$ tar xvf crc-linux-amd64.tar.xz +---- ++ +.. Create the [filename]*_~/bin_* directory if it does not exist and copy the [command]`{bin}` executable to it: ++ +[subs="attributes"] +---- +$ mkdir -p ~/bin +$ cp ~/Downloads/crc-linux-*-amd64/{bin} ~/bin +---- ++ +.. Add the [filename]*_~/bin_* directory to your `$PATH`: ++ +[subs="attributes"] +---- +$ export PATH=$PATH:$HOME/bin +$ echo 'export PATH=$PATH:$HOME/bin' >> ~/.bashrc +---- + +== Configuring usage data collection + +{prod} prompts you before use for link:{telemetry-notice-url}[optional, anonymous usage data collection to assist with development]. +No personally identifiable information is collected. + +[id='consenting-usage-data-collection'] +=== Consenting usage data collection + +You can grant consent for usage data collection at any time. + +.Procedure +. Configure {prod} to grant consent for usage data collection. ++ +[subs="+quotes,attributes"] +---- +$ {bin} config set consent-telemetry yes +---- +. Restart your {prod} instance to enable the change. ++ +[subs="+quotes,attributes"] +---- +$ {bin} stop +$ {bin} start +---- + +[id='revoking-usage-data-collection'] +=== Revoking usage data collection + +You can revoke consent for usage data collection at any time. + +.Procedure +. Configure {prod} to revoke consent for usage data collection. ++ +[subs="+quotes,attributes"] +---- +$ {bin} config set consent-telemetry no +---- +. Restart your {prod} instance to enable the change. ++ +[subs="+quotes,attributes"] +---- +$ {bin} stop +$ {bin} start +---- + +.Additional resources +* link:{telemetry-notice-url}[{rh} Telemetry data collection notice]. + +[id='upgrading'] +== Upgrading {prod} + +Newer versions of the {prod} executable require manual set up to prevent potential incompatibilities with earlier versions. + +.Procedure +. link:{crc-download-url}[Download the latest {prod} release]. + +. Save any desired information stored in your existing instance. + +. Delete the existing {prod} instance. ++ +[subs="+quotes,attributes"] +---- +$ {bin} delete +---- + +. Replace the earlier [command]`{bin}` executable with the executable of the latest release. +Verify that the new [command]`{bin}` executable is in use by checking its version: ++ +[subs="+quotes,attributes"] +---- +$ {bin} version +---- + +. Set up the new {prod} release: ++ +[subs="+quotes,attributes"] +---- +$ {bin} setup +---- + +. Start the new {prod} instance: ++ +[subs="+quotes,attributes"] +---- +$ {bin} start +---- diff --git a/modules/getting_started/partials/con_differences-from-production-openshift-install.adoc b/modules/ROOT/pages/introducing.adoc similarity index 62% rename from modules/getting_started/partials/con_differences-from-production-openshift-install.adoc rename to modules/ROOT/pages/introducing.adoc index d3ffa65..c1bc51e 100644 --- a/modules/getting_started/partials/con_differences-from-production-openshift-install.adoc +++ b/modules/ROOT/pages/introducing.adoc @@ -1,4 +1,20 @@ -= Differences from a production {ocp} installation +:description: Introducing {prod} += Introducing {rh-prod} + +[id='about'] +== About {prod} + +{rh-prod} brings a minimal {ocp} 4 cluster to your local computer. +This runtime provides minimal environments for development and testing purposes. +{prod} is mainly targeted at running on developers' desktops. +For other {ocp} use cases, such as headless or multi-developer setups, use the link:{openshift-installer-url}[full {openshift} installer]. + +See the link:{openshift-docs-url-landing-page}[{ocp} documentation] for a full introduction to {ocp}. + +{prod} includes the [command]`{bin}` command-line interface (CLI) to interact with the {prod} instance using the desired container runtime. + +[id='differences'] +== Differences from a production {ocp} installation The {openshift} preset for {rh-prod} provides a regular {ocp} installation with the following notable differences: diff --git a/modules/ROOT/pages/networking.adoc b/modules/ROOT/pages/networking.adoc new file mode 100644 index 0000000..202f20c --- /dev/null +++ b/modules/ROOT/pages/networking.adoc @@ -0,0 +1,307 @@ +:description: Networking += Networking + +== DNS configuration details + +=== General DNS setup + +The {ocp} cluster managed by {prod} uses 2 DNS domain names, `crc.testing` and `apps-crc.testing`. +The `crc.testing` domain is for core {ocp} services. +The `apps-crc.testing` domain is for accessing {openshift} applications deployed on the cluster. + +For example, the {ocp} API server is exposed as `api.crc.testing` while the {ocp} console is accessed as `console-openshift-console.apps-crc.testing`. +These DNS domains are served by a `dnsmasq` DNS container running inside the {prod} instance. + +The [command]`{bin} setup` command detects and adjusts your system DNS configuration so that it can resolve these domains. +Additional checks are done to verify DNS is properly configured when running [command]`{bin} start`. + +=== DNS on Linux + +On Linux, depending on your distribution, {prod} expects the following DNS configuration: + +==== NetworkManager + systemd-resolved + +This configuration is used by default on Fedora 33 or newer, and on Ubuntu Desktop editions. + +* {prod} expects NetworkManager to manage networking. +* {prod} configures `systemd-resolved` to forward requests for the `testing` domain to the `192.168.130.11` DNS server. +`192.168.130.11` is the IP of the {prod} instance. +* `systemd-resolved` configuration is done with a NetworkManager dispatcher script in [filename]*_/etc/NetworkManager/dispatcher.d/99-crc.sh_*: ++ +---- +#!/bin/sh + +export LC_ALL=C + +systemd-resolve --interface crc --set-dns 192.168.130.11 --set-domain ~testing + +exit 0 +---- + +[NOTE] +==== +`systemd-resolved` is also available as an unsupported Technology Preview on {rhel} and {centos} 8.3. +After {rhel-resolved-docs}[configuring the host] to use `systemd-resolved`, stop any running clusters and rerun [command]`{bin} setup`. +==== + +==== NetworkManager + dnsmasq + +This configuration is used by default on Fedora 32 or older, on {rhel}, and on {centos}. + +* {prod} expects NetworkManager to manage networking. +* NetworkManager uses `dnsmasq` with the [filename]*_/etc/NetworkManager/conf.d/crc-nm-dnsmasq.conf_* configuration file. +* The configuration file for this `dnsmasq` instance is [filename]*_/etc/NetworkManager/dnsmasq.d/crc.conf_*: ++ +---- +server=/crc.testing/192.168.130.11 +server=/apps-crc.testing/192.168.130.11 +---- + +** The NetworkManager `dnsmasq` instance forwards requests for the `crc.testing` and `apps-crc.testing` domains to the `192.168.130.11` DNS server. + +== Reserved IP subnets + +The {ocp} cluster managed by {prod} reserves IP subnets for internal use, which should not collide with your host network. +Ensure that the following IP subnets are available for use: + +.Reserved IP subnets +* `10.217.0.0/22` +* `10.217.4.0/23` +* `192.168.126.0/24` + +Additionally, the host hypervisor might reserve another IP subnet depending on the host operating system. +No additional subnet is reserved on {mac} and {msw}. +The additional reserved subnet for Linux is `192.168.130.0/24`. + +== Starting {prod} behind a proxy + +You can start {prod} behind a defined proxy using environment variables or configurable properties. + +[NOTE] +==== +SOCKS proxies are not supported by {ocp}. +==== + +.Prerequisites +* If you are not using [command]`crc oc-env`, when interacting with the cluster, export the `.testing` domain as part of the `no_proxy` environment variable. +The embedded [command]`oc` executable does not require manual settings. +For more information about using the embedded [command]`oc` executable, see xref:using.adoc#accessing-the-openshift-cluster-with-the-openshift-cli[Accessing the {openshift} cluster with the {openshift} CLI]. + +.Procedure +. Define a proxy using the `http_proxy` and `https_proxy` environment variables or using the [command]`{bin} config set` command as follows: ++ +[subs="+quotes,attributes"] +---- +$ {bin} config set http-proxy http://proxy.example.com:____ +$ {bin} config set https-proxy http://proxy.example.com:____ +$ {bin} config set no-proxy ____ +---- + +. If the proxy uses a custom CA certificate file, set it as follows: ++ +[subs="+quotes,attributes"] +---- +$ {bin} config set proxy-ca-file ____ +---- + +[NOTE] +==== +Proxy-related values set in the configuration for {prod} have priority over values set with environment variables. +==== + +== Accessing services running on your host from {prod} + +When you run services on your host, you can configure {prod} to access these services. + +.Prerequisites +* You have a service which is running on your host and want to consume it with {prod}. +* You are using the user mode network. On {mac} and {msw} this is the default behavior. + + +.Procedure +. Enable accessing services from host to {prod}: ++ +---- +$ crc config set host-network-access true +---- + +. Verify that the {prod} configuration uses user network mode and enables host network access: ++ +---- +$ crc config view +[...] +- network-mode : user +- host-network-access : true +[...] +---- + +. If {prod} instance is already running then restart it (stop => start), otherwise just start it. ++ +---- +$ crc stop && crc start +---- + +.Verification +Assuming your service is running on the host on port `8080`, to access +it from the {prod} instance, use `host.crc.testing:8080`. + +[id='setting-up-on-a-remote-server'] +== Setting up {prod} on a remote server + +Configure a remote server to run an {ocp} cluster provided by {prod}. + +This procedure assumes the use of a {rhel}, {fed}, or {centos} server. +Run every command in this procedure on the remote server. + +[WARNING] +==== +**Perform this procedure only on a local network.** +Exposing an insecure server on the internet has many security implications. +==== + +.Prerequisites +* {prod} is installed and set up on the remote server. +For more information, see xref:installing.adoc[Installing {prod}] and xref:using.adoc#setting-up[Setting up {prod}]. +* {prod} is configured to use the {openshift} preset on the remote server. +For more information, see xref:configuring.adoc#changing-the-selected-preset[Changing the selected preset]. +* Your user account has `sudo` permissions on the remote server. + +.Procedure +. Start the cluster: ++ +[subs="+quotes,attributes"] +---- +$ {bin} start +---- ++ +Ensure that the cluster remains running during this procedure. + +. Install the [package]`haproxy` package and other utilities: ++ +---- +$ sudo dnf install haproxy /usr/sbin/semanage +---- + +. Modify the firewall to allow communication with the cluster: ++ +---- +$ sudo systemctl enable --now firewalld +$ sudo firewall-cmd --add-service=http --permanent +$ sudo firewall-cmd --add-service=https --permanent +$ sudo firewall-cmd --add-service=kube-apiserver --permanent +$ sudo firewall-cmd --reload +---- + +. For SELinux, allow HAProxy to listen on TCP port 6443 to serve `kube-apiserver` on this port: ++ +---- +$ sudo semanage port -a -t http_port_t -p tcp 6443 +---- + +. Create a backup of the default [application]`haproxy` configuration: ++ +---- +$ sudo cp /etc/haproxy/haproxy.cfg{,.bak} +---- + +. Configure [application]`haproxy` for use with the cluster: ++ +[subs="+quotes,attributes"] +---- +$ export CRC_IP=$({bin} ip) +$ sudo tee /etc/haproxy/haproxy.cfg &>/dev/null </dev/null </dev/null <_` where `__` is the name of the node printed in the previous step. + +[id='troubleshooting-expired-certificates'] +== Troubleshooting expired certificates + +The system bundle of {ocp} in each released [command]`{bin}` executable expires 1 year after the release. +This expiration is due to certificates embedded in the {ocp} cluster. +The [command]`{bin} start` command triggers an automatic certificate renewal process when needed. +Certificate renewal can add up to five minutes to the start time of the cluster. + +To avoid this additional startup time, or in case of failures in the certificate renewal process, use the following procedure: + +.Procedure +To resolve expired certificate errors that cannot be automatically renewed: + +. link:{crc-download-url}[Download the latest {prod} release] and place the [command]`{bin}` executable in your `$PATH`. + +. Save any desired information stored in your existing instance. + +. Delete the existing {prod} instance. ++ +[subs="+quotes,attributes"] +---- +$ {bin} delete +---- + +. Set up the new release: ++ +[subs="+quotes,attributes"] +---- +$ {bin} setup +---- + +. Start the new instance: ++ +[subs="+quotes,attributes"] +---- +$ {bin} start +---- + +[id='troubleshooting-bundle-version-mismatch'] +== Troubleshooting bundle version mismatch + +Created {prod} instances contain bundle information and instance data. +Bundle information and instance data is not updated when setting up a new {prod} release. +This information is not updated due to customization in the earlier instance data. +This will lead to errors when running the [command]`{bin} start` command: + +[subs="+quotes,attributes"] +---- +$ {bin} start +... +FATA Bundle 'crc_hyperkit_4.2.8.crcbundle' was requested, but the existing VM is using +'crc_hyperkit_4.2.2.crcbundle' +---- + +.Procedure +. Save any desired information stored in your existing instance. + +. Delete the existing {prod} instance. ++ +[subs="+quotes,attributes"] +---- +$ {bin} delete +---- + +. Start a new {prod} instance: ++ +[subs="+quotes,attributes"] +---- +$ {bin} start +---- + +[id='troubleshooting-unknown-issues'] +== Troubleshooting unknown issues + +Resolve most issues by restarting {prod} with a clean state. +This involves stopping the instance, deleting it, reverting changes made by the [command]`{bin} setup` command, reapplying those changes, and restarting the instance. + +.Prerequisites +* You have xref:using.adoc#setting-up[set up {prod}]. +* You have xref:using.adoc#starting-the-instance[started the {prod} instance]. +* You are using the latest {prod} release. +Using a version earlier than {prod} 1.2.0 might result in errors related to expired x509 certificates. +For more information, see xref:troubleshooting-expired-certificates[Troubleshooting expired certificates]. + +.Procedure +To troubleshoot {prod}, perform the following steps: + +. Stop the {prod} instance: ++ +[subs="+quotes,attributes"] +---- +$ {bin} stop +---- + +. Save any desired information stored in your existing instance. + +. Delete the existing {prod} instance. ++ +[subs="+quotes,attributes"] +---- +$ {bin} delete +---- + +. Clean up remaining changes from the [command]`{bin} setup` command: ++ +[subs="+quotes,attributes"] +---- +$ {bin} cleanup +---- ++ +[NOTE] +==== +The [command]`{bin} cleanup` command removes an existing {prod} instance and reverts changes to DNS entries created by the [command]`{bin} setup` command. +==== + +. Set up your host machine to reapply the changes: ++ +[subs="+quotes,attributes"] +---- +$ {bin} setup +---- + +. Start the {prod} instance: ++ +[subs="+quotes,attributes"] +---- +$ {bin} start +---- ++ +[NOTE] +==== +The cluster takes a minimum of four minutes to start the necessary containers and Operators before serving a request. +==== + +If your issue is not resolved by this procedure, perform the following steps: + +. link:https://github.com/crc-org/crc/issues[Search open issues] for the issue that you are encountering. +. If no existing issue addresses the encountered issue, link:https://github.com/crc-org/crc/issues/new[create an issue] and link:https://help.github.com/en/articles/file-attachments-on-issues-and-pull-requests[attach the [filename]*_~/.crc/crc.log_* file] to the created issue. +The [filename]*_~/.crc/crc.log_* file has detailed debugging and troubleshooting information which can help diagnose the problem that you are experiencing. diff --git a/modules/ROOT/pages/using.adoc b/modules/ROOT/pages/using.adoc new file mode 100644 index 0000000..303ce2c --- /dev/null +++ b/modules/ROOT/pages/using.adoc @@ -0,0 +1,391 @@ +:description: Using {prod} +[id="using_{context}"] += Using {prod} + +[id='about-presets'] +== About presets + +[role="_abstract"] +{prod} presets represent a managed container runtime, and the lower bounds of system resources required by the instance to run it. +{prod} offers presets for: + +`openshift`:: {ocp} +`okd`:: {okd} +`microshift`:: {ushift} + +On {msw} and {mac}, the {prod} guided installer prompts you for your desired preset. +On Linux, the {ocp} preset is selected by default. +You can change this selection using the [command]`{bin} config` command before running the [command]`{bin} setup` command. +Only one preset can be active at a time. + +[role="_additional-resources"] +.Additional resources +* xref:installing.adoc#minimum-system-requirements[Minimum system requirements]. +* xref:configuring.adoc#changing-the-selected-preset[Changing the selected preset]. + +[id='setting-up'] +== Setting up {prod} + +[role="_abstract"] +The [command]`{bin} setup` command performs operations to set up the environment of your host machine for the {prod} instance. + +The [command]`{bin} setup` command creates the [filename]*_~/.crc_* directory if it does not already exist. + +[WARNING] +==== +If you are setting up a new version, capture any changes made to the instance before setting up a new {prod} release. +==== + +.Prerequisites +* On Linux or {mac}, ensure that your user account has permission to use the [command]`sudo` command. +On {msw}, ensure that your user account can elevate to Administrator privileges. + +[NOTE] +==== +Do not run the [command]`{bin}` executable as the `root` user or an administrator. +Always run the [command]`{bin}` executable with your user account. +==== + +.Procedure +. Set up your host machine for {prod}: ++ +[subs="+quotes,attributes"] +---- +$ {bin} setup +---- + +[role="_additional-resources"] +.Additional resources +* xref:about-presets[About presets]. + +[id='starting-the-instance'] +== Starting the instance + +The [command]`{bin} start` command starts the {prod} instance and configured container runtime. + +.Prerequisites +* To avoid networking-related issues, ensure that you are not connected to a VPN and that your network connection is reliable. +* You have xref:setting-up[set up {prod}]. +* On {msw}, ensure that your user account can elevate to Administrator privileges. +* For the {openshift} preset, ensure that you have a valid {openshift} user pull secret. +Copy or download the pull secret from the Pull Secret section of the link:https://console.redhat.com/openshift/create/local[{prod} page on the {rh} Hybrid Cloud Console]. ++ +[NOTE] +==== +Accessing the user pull secret requires a Red Hat account. +==== + +.Procedure +. Start the {prod} instance: ++ +[subs="+quotes,attributes"] +---- +$ {bin} start +---- + +. For the {openshift} preset, supply your user pull secret when prompted. ++ +[NOTE] +==== +The cluster takes a minimum of four minutes to start the necessary containers and Operators before serving a request. +==== + +.Additional resources +* xref:configuring.adoc#configuring-the-instance[Configuring the resources allocated to the instance]. +* If you see errors during [command]`{bin} start`, see the xref:troubleshooting.adoc[Troubleshooting {prod}] section for potential solutions. + +[id='accessing-the-openshift-cluster'] +== Accessing the {openshift} cluster + +Access the {ocp} cluster running in the {prod} instance by using the {ocp} web console or {openshift} CLI ([command]`oc`). + +[id='accessing-the-openshift-web-console'] +=== Accessing the {openshift} web console + +Access the {ocp} web console by using your web browser. + +Access the cluster by using either the `kubeadmin` or `developer` user. +Use the `developer` user for creating projects or {openshift} applications and for application deployment. +Use the `kubeadmin` user only for administrative tasks such as creating new users or setting roles. + +.Prerequisites +* {prod} is configured to use the {openshift} preset. +See: xref:configuring.adoc#changing-the-selected-preset[Changing the selected preset]. +* A running {prod} instance. +See: xref:starting-the-instance[Starting the instance]. + +.Procedure +. To access the {ocp} web console with your default web browser, run the following command: ++ +[subs="+quotes,attributes"] +---- +$ {bin} console +---- + +. Log in as the `developer` user with the password printed in the output of the [command]`{bin} start` command. +You can also view the password for the `developer` and `kubeadmin` users by running the following command: ++ +[subs="+quotes,attributes"] +---- +$ {bin} console --credentials +---- + +See xref:troubleshooting.adoc[Troubleshooting {prod}] if you cannot access the {ocp} cluster managed by {prod}. + +.Additional resources +* The link:https://docs.openshift.com/container-platform/latest/applications/projects/working-with-projects.html[{ocp} documentation] covers the creation of projects and applications. + +[id='accessing-the-openshift-cluster-with-the-openshift-cli'] +=== Accessing the {openshift} cluster with the {openshift} CLI + +Access the {ocp} cluster managed by {prod} by using the {openshift} CLI ([command]`oc`). + +.Prerequisites +* {prod} is configured to use the {openshift} preset. +See: xref:configuring.adoc#changing-the-selected-preset[Changing the selected preset]. +* A running {prod} instance. +See: xref:starting-the-instance[Starting the instance]. + +.Procedure +. Run the [command]`{bin} oc-env` command to print the command needed to add the cached [command]`oc` executable to your `$PATH`: ++ +[subs="+quotes,attributes"] +---- +$ {bin} oc-env +---- + +. Run the printed command. + +. Log in as the `developer` user: ++ +[subs="+quotes,attributes"] +---- +$ oc login -u developer https://api.crc.testing:6443 +---- ++ +[NOTE] +==== +The [command]`{bin} start` command prints the password for the `developer` user. +You can also view it by running the [command]`{bin} console --credentials` command. +==== + +. You can now use [command]`oc` to interact with your {ocp} cluster. +For example, to verify that the {ocp} cluster Operators are available, log in as the `kubeadmin` user and run the following command: ++ +[subs="+quotes,attributes",options="nowrap"] +---- +$ oc config use-context crc-admin +$ oc whoami +kubeadmin +$ oc get co +---- ++ +[NOTE] +==== +{prod} disables the Cluster Monitoring Operator by default. +==== + +See xref:troubleshooting.adoc[Troubleshooting {prod}] if you cannot access the {ocp} cluster managed by {prod}. + +.Additional resources +* The link:https://docs.openshift.com/container-platform/latest/applications/projects/working-with-projects.html[{ocp} documentation] covers the creation of projects and applications. + +[id='accessing-the-internal-openshift-registry'] +=== Accessing the internal {openshift} registry + +The {ocp} cluster running in the {prod} instance includes an internal container image registry by default. +This internal container image registry can be used as a publication target for locally developed container images. +To access the internal {ocp} registry, follow these steps. + +.Prerequisites +* {prod} is configured to use the {openshift} preset. +See: xref:configuring.adoc#changing-the-selected-preset[Changing the selected preset]. +* A running {prod} instance. +See: xref:starting-the-instance[Starting the instance]. +* A working {openshift} CLI ([command]`oc`) command. +See: xref:accessing-the-openshift-cluster-with-the-openshift-cli[Accessing the {openshift} cluster with the {openshift} CLI]. + +.Procedure +. Check which user is logged in to the cluster: ++ +[subs="+quotes,attributes"] +---- +$ oc whoami +---- ++ +[NOTE] +==== +For demonstration purposes, the current user is assumed to be `kubeadmin`. +==== + +. Log in to the registry as that user with its token: ++ +[subs="+quotes,attributes"] +---- +$ oc registry login --insecure=true +---- + +. Create a new project: ++ +[subs="+quotes,attributes"] +---- +$ oc new-project demo +---- + +. Mirror an example container image: ++ +[subs="+quotes,attributes"] +---- +$ oc image mirror registry.access.redhat.com/ubi8/ubi:latest=default-route-openshift-image-registry.apps-crc.testing/demo/ubi8:latest --insecure=true --filter-by-os=linux/amd64 +---- + +. Get imagestreams and verify that the pushed image is listed: ++ +[subs="+quotes,attributes"] +---- +$ oc get is +---- + +. Enable image lookup in the imagestream: ++ +[subs="+quotes,attributes"] +---- +$ oc set image-lookup ubi8 +---- ++ +This setting allows the imagestream to be the source of images without having to provide the full URL to the internal registry. + +. Create a pod using the recently pushed image: ++ +[subs="+quotes,attributes"] +---- +$ oc run demo --image=ubi8 --command -- sleep 600s +---- + +[id='deploying-a-sample-application-with-odo'] +== Deploying a sample application with `odo` + +You can use [command]`odo` to create {openshift} projects and applications from the command line. +This procedure deploys a sample application to the {ocp} cluster running in the {prod} instance. + +.Prerequisites +* You have installed [command]`odo`. +For more information, see link:{odo-docs-url-installing}[Installing `odo`] in the [command]`odo` documentation. +* {prod} is configured to use the {openshift} preset. +See: xref:configuring.adoc#changing-the-selected-preset[Changing the selected preset]. +* The {prod} instance is running. +See: xref:starting-the-instance[Starting the instance]. + +.Procedure +. Log in to the running {ocp} cluster managed by {prod} as the `developer` user: ++ +[subs="+quotes,attributes"] +---- +$ odo login -u developer -p developer +---- + +. Create a project for your application: ++ +[subs="+quotes,attributes"] +---- +$ odo project create sample-app +---- + +. Create a directory for your components: ++ +[subs="+quotes,attributes"] +---- +$ mkdir sample-app +$ cd sample-app +---- + +. Clone an example Node.js application: ++ +[subs="+quotes,attributes"] +---- +$ git clone https://github.com/openshift/nodejs-ex +$ cd nodejs-ex +---- + +. Add a `nodejs` component to the application: ++ +[subs="+quotes,attributes"] +---- +$ odo create nodejs +---- + +. Create a URL and add an entry to the local configuration file: ++ +[subs="+quotes,attributes"] +---- +$ odo url create --port 8080 +---- + +. Push the changes: ++ +[subs="+quotes,attributes"] +---- +$ odo push +---- ++ +Your component is now deployed to the cluster with an accessible URL. + +. List the URLs and check the desired URL for the component: ++ +[subs="+quotes,attributes"] +---- +$ odo url list +---- + +. View the deployed application using the generated URL. + +.Additional resources +* For more information about using [command]`odo`, see the link:{odo-docs-url}[`odo` documentation]. + +[id='stopping-the-instance'] +== Stopping the instance + +The [command]`{bin} stop` command stops the running {prod} instance and container runtime. +The stopping process takes a few minutes while the cluster shuts down. + +.Procedure +* Stop the {prod} instance and container runtime: ++ +[subs="+quotes,attributes"] +---- +$ {bin} stop +---- + +[id='restarting-the-instance'] +== Restarting the instance + +To restart {prod}, stop the instance and start it again. + +.Procedure +. Stop the {prod} instance: ++ +[subs="+quotes,attributes"] +---- +$ {bin} stop +---- +. Start the {prod} instance: ++ +[subs="+quotes,attributes"] +---- +$ {bin} start +---- + +[id='deleting-the-instance'] +== Deleting the instance + +The [command]`{bin} delete` command deletes an existing {prod} instance. + +.Procedure +. Save any desired information stored in your existing instance. + +. Delete the existing {prod} instance. ++ +[subs="+quotes,attributes"] +---- +$ {bin} delete +---- diff --git a/modules/getting_started/examples/snip_crc_preset_list.adoc b/modules/getting_started/examples/snip_crc_preset_list.adoc deleted file mode 100644 index 1ea5c6f..0000000 --- a/modules/getting_started/examples/snip_crc_preset_list.adoc +++ /dev/null @@ -1,3 +0,0 @@ -`openshift`:: {ocp} -`okd`:: {okd} -`microshift`:: {ushift} diff --git a/modules/getting_started/examples/snip_crc_preset_names.adoc b/modules/getting_started/examples/snip_crc_preset_names.adoc deleted file mode 100644 index 332bebb..0000000 --- a/modules/getting_started/examples/snip_crc_preset_names.adoc +++ /dev/null @@ -1,8 +0,0 @@ -.Preset names -[%header,format=csv,cols="1,2"] -|=== -Name, Preset -`openshift`, {ocp} -`okd`, {okd} -`microshift`, {ushift} -|=== diff --git a/modules/getting_started/examples/snip_crc_preset_platforms.adoc b/modules/getting_started/examples/snip_crc_preset_platforms.adoc deleted file mode 100644 index 24898b5..0000000 --- a/modules/getting_started/examples/snip_crc_preset_platforms.adoc +++ /dev/null @@ -1,8 +0,0 @@ -.Preset and architecture compatibility -[%header,format=csv,cols="3,1,1,1"] -|=== -Preset, AMD64, Intel 64, Apple silicon -{ocp}, yes, yes, yes -{okd}, yes, yes, no -{ushift}, yes, yes, yes -|=== diff --git a/modules/getting_started/pages/administrative-tasks.adoc b/modules/getting_started/pages/administrative-tasks.adoc deleted file mode 100644 index b6105e3..0000000 --- a/modules/getting_started/pages/administrative-tasks.adoc +++ /dev/null @@ -1,8 +0,0 @@ -:description: Administrative tasks - -[id="administrative-tasks_{context}"] -= Administrative tasks - -include::partial$proc_starting-monitoring.adoc[leveloffset=+1] - -include::partial$proc_enabling-override-operators.adoc[leveloffset=+1] diff --git a/modules/getting_started/pages/configuring.adoc b/modules/getting_started/pages/configuring.adoc deleted file mode 100644 index a39165c..0000000 --- a/modules/getting_started/pages/configuring.adoc +++ /dev/null @@ -1,12 +0,0 @@ -:description: Configuring {prod} - -[id="configuring_{context}"] -= Configuring {prod} - -include::partial$con_about-configuration.adoc[leveloffset=+1] - -include::partial$proc_viewing-configuration.adoc[leveloffset=+1] - -include::partial$proc_changing-the-selected-preset.adoc[leveloffset=+1] - -include::partial$proc_configuring-the-instance.adoc[leveloffset=+1] diff --git a/modules/getting_started/pages/installing.adoc b/modules/getting_started/pages/installing.adoc deleted file mode 100644 index 2f3f824..0000000 --- a/modules/getting_started/pages/installing.adoc +++ /dev/null @@ -1,16 +0,0 @@ -:description: Installing {prod} - -[id="installation_{context}"] -= Installing {prod} - -include::partial$ref_minimum-system-requirements.adoc[leveloffset=+1] - -include::partial$ref_required-software-packages.adoc[leveloffset=+1] - -include::partial$proc_installing.adoc[leveloffset=+1] - -include::partial$con_about-usage-data-collection.adoc[leveloffset=+1] - -include::partial$proc_configuring-usage-data-collection.adoc[leveloffset=+1] - -include::partial$proc_upgrading.adoc[leveloffset=+1] diff --git a/modules/getting_started/pages/introducing.adoc b/modules/getting_started/pages/introducing.adoc deleted file mode 100644 index cbfc4ef..0000000 --- a/modules/getting_started/pages/introducing.adoc +++ /dev/null @@ -1,8 +0,0 @@ -:description: Introducing {prod} - -[id="introducing_{context}"] -= Introducing {rh-prod} - -include::partial$con_about.adoc[leveloffset=+1] - -include::partial$con_differences-from-production-openshift-install.adoc[leveloffset=+1] diff --git a/modules/getting_started/pages/networking.adoc b/modules/getting_started/pages/networking.adoc deleted file mode 100644 index d92f1ea..0000000 --- a/modules/getting_started/pages/networking.adoc +++ /dev/null @@ -1,16 +0,0 @@ -:description: Networking - -[id="networking_{context}"] -= Networking - -include::partial$ref_dns-configuration.adoc[leveloffset=+1] - -include::partial$ref_reserved-ip-subnets.adoc[leveloffset=+1] - -include::partial$proc_starting-behind-proxy.adoc[leveloffset=+1] - -include::partial$proc_connecting-to-host.adoc[leveloffset=+1] - -include::partial$proc_setting-up-remote-server.adoc[leveloffset=+1] - -include::partial$proc_connecting-to-remote-instance.adoc[leveloffset=+1] diff --git a/modules/getting_started/pages/troubleshooting.adoc b/modules/getting_started/pages/troubleshooting.adoc deleted file mode 100644 index 3134229..0000000 --- a/modules/getting_started/pages/troubleshooting.adoc +++ /dev/null @@ -1,19 +0,0 @@ -:description: Troubleshooting {prod} - -[id="troubleshooting_{context}"] -= Troubleshooting {rh-prod} - -[NOTE] -==== -The goal of {rh-prod} is to deliver an {ocp} environment for development and testing purposes. -Issues occurring during installation or usage of specific {openshift} applications are outside of the scope of {prod}. -Report such issues to the relevant project. -==== - -include::partial$proc_getting-shell-access-to-the-openshift-cluster.adoc[leveloffset=+1] - -include::partial$proc_troubleshooting-expired-certificates.adoc[leveloffset=+1] - -include::partial$proc_troubleshooting-bundle-version-mismatch.adoc[leveloffset=+1] - -include::partial$proc_troubleshooting-unknown-issues.adoc[leveloffset=+1] diff --git a/modules/getting_started/pages/using.adoc b/modules/getting_started/pages/using.adoc deleted file mode 100644 index 1c018e8..0000000 --- a/modules/getting_started/pages/using.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="using_{context}"] -= Using {prod} - -include::partial$con_about-presets.adoc[leveloffset=+1] - -include::partial$proc_setting-up.adoc[leveloffset=+1] - -include::partial$proc_starting-the-instance.adoc[leveloffset=+1] - -include::partial$assembly_accessing-the-openshift-cluster.adoc[leveloffset=+1] - -include::partial$proc_deploying-sample-application-with-odo.adoc[leveloffset=+1] - -include::partial$proc_stopping-the-instance.adoc[leveloffset=+1] - -include::partial$proc_deleting-the-instance.adoc[leveloffset=+1] diff --git a/modules/getting_started/partials/assembly_accessing-the-openshift-cluster.adoc b/modules/getting_started/partials/assembly_accessing-the-openshift-cluster.adoc deleted file mode 100644 index 6fe9592..0000000 --- a/modules/getting_started/partials/assembly_accessing-the-openshift-cluster.adoc +++ /dev/null @@ -1,9 +0,0 @@ -= Accessing the {openshift} cluster - -Access the {ocp} cluster running in the {prod} instance by using the {ocp} web console or {openshift} CLI ([command]`oc`). - -include::partial$proc_accessing-the-openshift-web-console.adoc[leveloffset=+1] - -include::partial$proc_accessing-the-openshift-cluster-with-oc.adoc[leveloffset=+1] - -include::partial$proc_accessing-the-internal-openshift-registry.adoc[leveloffset=+1] diff --git a/modules/getting_started/partials/con_about-configuration.adoc b/modules/getting_started/partials/con_about-configuration.adoc deleted file mode 100644 index f5cf8c4..0000000 --- a/modules/getting_started/partials/con_about-configuration.adoc +++ /dev/null @@ -1,11 +0,0 @@ -= About {prod} configuration - -Use the [command]`{bin} config` command to configure both the [command]`{bin}` executable and the {prod} instance. -The [command]`{bin} config` command requires a subcommand to act on the configuration. -The available subcommands are `get`, `set,` `unset`, and `view`. -The `get`, `set`, and `unset` subcommands operate on named configurable properties. -Run the [command]`{bin} config --help` command to list the available properties. - -You can also use the [command]`{bin} config` command to configure the behavior of the startup checks for the [command]`{bin} start` and [command]`{bin} setup` commands. -By default, startup checks report an error and stop execution when their conditions are not met. -Set the value of a property starting with `skip-check` to `true` to skip the check. diff --git a/modules/getting_started/partials/con_about-presets.adoc b/modules/getting_started/partials/con_about-presets.adoc deleted file mode 100644 index 8698302..0000000 --- a/modules/getting_started/partials/con_about-presets.adoc +++ /dev/null @@ -1,17 +0,0 @@ -= About presets - -[role="_abstract"] -{prod} presets represent a managed container runtime, and the lower bounds of system resources required by the instance to run it. -{prod} offers presets for: - -include::example$snip_{project-context}_preset_list.adoc[] - -On {msw} and {mac}, the {prod} guided installer prompts you for your desired preset. -On Linux, the {ocp} preset is selected by default. -You can change this selection using the [command]`{bin} config` command before running the [command]`{bin} setup` command. -Only one preset can be active at a time. - -[role="_additional-resources"] -.Additional resources -* For more information about the minimum system requirements for each preset, see link:{crc-gsg-url}#minimum-system-requirements_gsg[Minimum system requirements]. -* For more information on changing the selected preset, see link:{crc-gsg-url}#changing-the-selected-preset_gsg[Changing the selected preset]. diff --git a/modules/getting_started/partials/con_about-usage-data-collection.adoc b/modules/getting_started/partials/con_about-usage-data-collection.adoc deleted file mode 100644 index 953fb52..0000000 --- a/modules/getting_started/partials/con_about-usage-data-collection.adoc +++ /dev/null @@ -1,10 +0,0 @@ -= About usage data collection - -{prod} prompts you before use for optional, anonymous usage data collection to assist with development. -No personally identifiable information is collected. -Consent for usage data collection can be granted or revoked by you at any time. - -[role="_additional-resources"] -.Additional resources -* For more information about collected data, see the {rh} link:{telemetry-notice-url}[Telemetry data collection notice]. -* To grant or revoke consent for usage data collection, see link:{crc-gsg-url}#configuring-usage-data-collection_gsg[Configuring usage data collection]. diff --git a/modules/getting_started/partials/con_about.adoc b/modules/getting_started/partials/con_about.adoc deleted file mode 100644 index b3e983c..0000000 --- a/modules/getting_started/partials/con_about.adoc +++ /dev/null @@ -1,10 +0,0 @@ -= About {prod} - -{rh-prod} brings a minimal {ocp} 4 cluster to your local computer. -This runtime provides minimal environments for development and testing purposes. -{prod} is mainly targeted at running on developers' desktops. -For other {ocp} use cases, such as headless or multi-developer setups, use the link:{openshift-installer-url}[full {openshift} installer]. - -See the link:{openshift-docs-url-landing-page}[{ocp} documentation] for a full introduction to {ocp}. - -{prod} includes the [command]`{bin}` command-line interface (CLI) to interact with the {prod} instance using the desired container runtime. diff --git a/modules/getting_started/partials/proc_accessing-the-internal-openshift-registry.adoc b/modules/getting_started/partials/proc_accessing-the-internal-openshift-registry.adoc deleted file mode 100644 index b9caa05..0000000 --- a/modules/getting_started/partials/proc_accessing-the-internal-openshift-registry.adoc +++ /dev/null @@ -1,70 +0,0 @@ -= Accessing the internal {openshift} registry - -The {ocp} cluster running in the {prod} instance includes an internal container image registry by default. -This internal container image registry can be used as a publication target for locally developed container images. -To access the internal {ocp} registry, follow these steps. - -.Prerequisites -* {prod} is configured to use the {openshift} preset. -For more information, see link:{crc-gsg-url}#changing-the-selected-preset_gsg[Changing the selected preset]. -* A running {prod} instance. -For more information, see link:{crc-gsg-url}#starting-the-instance_gsg[Starting the instance]. -* A working {openshift} CLI ([command]`oc`) command. -For more information, see link:{crc-gsg-url}#accessing-the-openshift-cluster-with-oc_gsg[Accessing the {openshift} cluster with the {openshift} CLI]. - -.Procedure -. Check which user is logged in to the cluster: -+ -[subs="+quotes,attributes"] ----- -$ oc whoami ----- -+ -[NOTE] -==== -For demonstration purposes, the current user is assumed to be `kubeadmin`. -==== - -. Log in to the registry as that user with its token: -+ -[subs="+quotes,attributes"] ----- -$ oc registry login --insecure=true ----- - -. Create a new project: -+ -[subs="+quotes,attributes"] ----- -$ oc new-project demo ----- - -. Mirror an example container image: -+ -[subs="+quotes,attributes"] ----- -$ oc image mirror registry.access.redhat.com/ubi8/ubi:latest=default-route-openshift-image-registry.apps-crc.testing/demo/ubi8:latest --insecure=true --filter-by-os=linux/amd64 ----- - -. Get imagestreams and verify that the pushed image is listed: -+ -[subs="+quotes,attributes"] ----- -$ oc get is ----- - -. Enable image lookup in the imagestream: -+ -[subs="+quotes,attributes"] ----- -$ oc set image-lookup ubi8 ----- -+ -This setting allows the imagestream to be the source of images without having to provide the full URL to the internal registry. - -. Create a pod using the recently pushed image: -+ -[subs="+quotes,attributes"] ----- -$ oc run demo --image=ubi8 --command -- sleep 600s ----- diff --git a/modules/getting_started/partials/proc_accessing-the-openshift-cluster-with-oc.adoc b/modules/getting_started/partials/proc_accessing-the-openshift-cluster-with-oc.adoc deleted file mode 100644 index 53f12f6..0000000 --- a/modules/getting_started/partials/proc_accessing-the-openshift-cluster-with-oc.adoc +++ /dev/null @@ -1,53 +0,0 @@ -= Accessing the {openshift} cluster with the {openshift} CLI - -Access the {ocp} cluster managed by {prod} by using the {openshift} CLI ([command]`oc`). - -.Prerequisites -* {prod} is configured to use the {openshift} preset. -For more information, see link:{crc-gsg-url}#changing-the-selected-preset_gsg[Changing the selected preset]. -* A running {prod} instance. -For more information, see link:{crc-gsg-url}#starting-the-instance_gsg[Starting the instance]. - -.Procedure -. Run the [command]`{bin} oc-env` command to print the command needed to add the cached [command]`oc` executable to your `$PATH`: -+ -[subs="+quotes,attributes"] ----- -$ {bin} oc-env ----- - -. Run the printed command. - -. Log in as the `developer` user: -+ -[subs="+quotes,attributes"] ----- -$ oc login -u developer https://api.crc.testing:6443 ----- -+ -[NOTE] -==== -The [command]`{bin} start` command prints the password for the `developer` user. -You can also view it by running the [command]`{bin} console --credentials` command. -==== - -. You can now use [command]`oc` to interact with your {ocp} cluster. -For example, to verify that the {ocp} cluster Operators are available, log in as the `kubeadmin` user and run the following command: -+ -[subs="+quotes,attributes",options="nowrap"] ----- -$ oc config use-context crc-admin -$ oc whoami -kubeadmin -$ oc get co ----- -+ -[NOTE] -==== -{prod} disables the Cluster Monitoring Operator by default. -==== - -See link:{crc-gsg-url}#troubleshooting_gsg[Troubleshooting {prod}] if you cannot access the {ocp} cluster managed by {prod}. - -.Additional resources -* The link:https://docs.openshift.com/container-platform/latest/applications/projects/working-with-projects.html[{ocp} documentation] covers the creation of projects and applications. diff --git a/modules/getting_started/partials/proc_accessing-the-openshift-web-console.adoc b/modules/getting_started/partials/proc_accessing-the-openshift-web-console.adoc deleted file mode 100644 index bd950df..0000000 --- a/modules/getting_started/partials/proc_accessing-the-openshift-web-console.adoc +++ /dev/null @@ -1,34 +0,0 @@ -= Accessing the {openshift} web console - -Access the {ocp} web console by using your web browser. - -Access the cluster by using either the `kubeadmin` or `developer` user. -Use the `developer` user for creating projects or {openshift} applications and for application deployment. -Use the `kubeadmin` user only for administrative tasks such as creating new users or setting roles. - -.Prerequisites -* {prod} is configured to use the {openshift} preset. -For more information, see link:{crc-gsg-url}#changing-the-selected-preset_gsg[Changing the selected preset]. -* A running {prod} instance. -For more information, see link:{crc-gsg-url}#starting-the-instance_gsg[Starting the instance]. - -.Procedure -. To access the {ocp} web console with your default web browser, run the following command: -+ -[subs="+quotes,attributes"] ----- -$ {bin} console ----- - -. Log in as the `developer` user with the password printed in the output of the [command]`{bin} start` command. -You can also view the password for the `developer` and `kubeadmin` users by running the following command: -+ -[subs="+quotes,attributes"] ----- -$ {bin} console --credentials ----- - -See link:{crc-gsg-url}#troubleshooting_gsg[Troubleshooting {prod}] if you cannot access the {ocp} cluster managed by {prod}. - -.Additional resources -* The link:https://docs.openshift.com/container-platform/latest/applications/projects/working-with-projects.html[{ocp} documentation] covers the creation of projects and applications. diff --git a/modules/getting_started/partials/proc_changing-the-selected-preset.adoc b/modules/getting_started/partials/proc_changing-the-selected-preset.adoc deleted file mode 100644 index 308fd4f..0000000 --- a/modules/getting_started/partials/proc_changing-the-selected-preset.adoc +++ /dev/null @@ -1,29 +0,0 @@ -= Changing the selected preset - -[role="_abstract"] -You can change the container runtime used for the {prod} instance by selecting the desired preset. - -You can change the selected preset using the command line interface. - -[IMPORTANT] -==== -You cannot change the preset of an existing {prod} instance. -Preset changes are only applied when a {prod} instance is created. -To enable preset changes, you must delete the existing instance and start a new one. -==== - -.Procedure -* Change the selected preset from the command line: -+ -[subs="+quotes,attributes"] ----- -$ {bin} config set preset ____ ----- -+ -Valid preset names are: -+ -include::example$snip_{project-context}_preset_names.adoc[] - -[role="_additional-resources"] -.Additional resources -* For more information about the minimum system requirements for each preset, see link:{crc-gsg-url}#minimum-system-requirements_gsg[Minimum system requirements]. diff --git a/modules/getting_started/partials/proc_configuring-the-instance.adoc b/modules/getting_started/partials/proc_configuring-the-instance.adoc deleted file mode 100644 index 6035d1b..0000000 --- a/modules/getting_started/partials/proc_configuring-the-instance.adoc +++ /dev/null @@ -1,52 +0,0 @@ -= Configuring the instance - -Use the `cpus` and `memory` properties to configure the default number of vCPUs and amount of memory available to the {prod} instance, respectively. - -Alternatively, the number of vCPUs and amount of memory can be assigned using the `--cpus` and `--memory` flags to the `{bin} start` command, respectively. - -[IMPORTANT] -==== -You cannot change the configuration of a running {prod} instance. -To enable configuration changes, you must stop the running instance and start it again. -==== - -.Procedure -* To configure the number of vCPUs available to the instance: -+ -[subs="+quotes,attributes"] ----- -$ {bin} config set cpus ____ ----- -+ -The default value for the `cpus` property is `4`. -The number of vCPUs to assign must be greater than or equal to the default. - -* To start the instance with the desired number of vCPUs: -+ -[subs="+quotes,attributes"] ----- -$ {bin} start --cpus ____ ----- - -* To configure the memory available to the instance: -+ -[subs="+quotes,attributes"] ----- -$ {bin} config set memory ____ ----- -+ -[NOTE] -==== -Values for available memory are set in mebibytes (MiB). -One gibibyte (GiB) of memory is equal to 1024 MiB. -==== -+ -The default value for the `memory` property is `10752`. -The amount of memory to assign must be greater than or equal to the default. - -* To start the instance with the desired amount of memory: -+ -[subs="+quotes,attributes"] ----- -$ {bin} start --memory ____ ----- diff --git a/modules/getting_started/partials/proc_configuring-usage-data-collection.adoc b/modules/getting_started/partials/proc_configuring-usage-data-collection.adoc deleted file mode 100644 index b83f021..0000000 --- a/modules/getting_started/partials/proc_configuring-usage-data-collection.adoc +++ /dev/null @@ -1,28 +0,0 @@ -= Configuring usage data collection - -Consent for usage data collection can be granted or revoked by you at any time using the following configuration commands. - -[NOTE] -==== -Changes to telemetry consent do not modify a running instance. -The change will take effect next time you run the [command]`{bin} start` command. -==== - -.Procedure -* To manually enable telemetry, run the following command: -+ -[subs="+quotes,attributes"] ----- -$ {bin} config set consent-telemetry yes ----- - -* To manually disable telemetry, run the following command: -+ -[subs="+quotes,attributes"] ----- -$ {bin} config set consent-telemetry no ----- - -[role="_additional-resources"] -.Additional resources -* For more information about the collected data, see the {rh} link:{telemetry-notice-url}[Telemetry data collection notice]. diff --git a/modules/getting_started/partials/proc_connecting-to-host.adoc b/modules/getting_started/partials/proc_connecting-to-host.adoc deleted file mode 100644 index feed0d7..0000000 --- a/modules/getting_started/partials/proc_connecting-to-host.adoc +++ /dev/null @@ -1,35 +0,0 @@ -= Accessing services running on your host from {prod} - -When you run services on your host, you can configure {prod} to access these services. - -.Prerequisites -* You have a service which is running on your host and want to consume it with {prod}. -* You are using the user mode network. On {mac} and {msw} this is the default behavior. - - -.Procedure -. Enable accessing services from host to {prod}: -+ ----- -$ crc config set host-network-access true ----- - -. Verify that the {prod} configuration uses user network mode and enables host network access: -+ ----- -$ crc config view -[...] -- network-mode : user -- host-network-access : true -[...] ----- - -. If {prod} instance is already running then restart it (stop => start), otherwise just start it. -+ ----- -$ crc stop && crc start ----- - -.Verification -Assuming your service is running on the host on port `8080`, to access -it from the {prod} instance, use `host.crc.testing:8080`. diff --git a/modules/getting_started/partials/proc_connecting-to-remote-instance.adoc b/modules/getting_started/partials/proc_connecting-to-remote-instance.adoc deleted file mode 100644 index 02e45fe..0000000 --- a/modules/getting_started/partials/proc_connecting-to-remote-instance.adoc +++ /dev/null @@ -1,63 +0,0 @@ -= Connecting to a remote {prod} instance - -Use [application]`dnsmasq` to connect a client machine to a remote server running an {ocp} cluster managed by {prod}. - -This procedure assumes the use of a {rhel}, {fed}, or {centos} client. -Run every command in this procedure on the client. - -[IMPORTANT] -==== -**Connect to a server that is only exposed on your local network.** -==== - -.Prerequisites -* A remote server is set up for the client to connect to. -For more information, see link:{crc-gsg-url}#setting-up-remote-server_gsg[Setting up {prod} on a remote server]. -* You know the external IP address of the server. -* You have the link:{oc-download-url}[latest {openshift} CLI ([command]`oc`)] in your `$PATH` on the client. - -.Procedure -. Install the [package]`dnsmasq` package: -+ ----- -$ sudo dnf install dnsmasq ----- - -. Enable the use of [application]`dnsmasq` for DNS resolution in NetworkManager: -+ ----- -$ sudo tee /etc/NetworkManager/conf.d/use-dnsmasq.conf &>/dev/null </dev/null < oc get clusterversion version -ojsonpath='{range .spec.overrides[*]}{.name}{"\n"}{end}' | % {$nl++;"`t$($nl-1) `t $_"};$nl=0 ----- - -. Start the desired Operator using the identified numeric index: -+ -[subs="+quotes"] ----- -$ oc patch clusterversion/version --type='json' -p '[{"op":"remove", "path":"/spec/overrides/__"}]' -clusterversion.config.openshift.io/version patched ----- diff --git a/modules/getting_started/partials/proc_getting-shell-access-to-the-openshift-cluster.adoc b/modules/getting_started/partials/proc_getting-shell-access-to-the-openshift-cluster.adoc deleted file mode 100644 index 88e8f4a..0000000 --- a/modules/getting_started/partials/proc_getting-shell-access-to-the-openshift-cluster.adoc +++ /dev/null @@ -1,25 +0,0 @@ -= Getting shell access to the {openshift} cluster - -To access the cluster for troubleshooting or debugging purposes, follow this procedure. - -[NOTE] -==== -Direct access to the {ocp} cluster is not needed for regular use and is strongly discouraged. -==== - -.Prerequisites -* Enable {openshift} CLI ([command]`oc`) access to the cluster and log in as the `kubeadmin` user. -For detailed steps, see link:{crc-gsg-url}#accessing-the-openshift-cluster-with-oc_gsg[Accessing the {openshift} cluster with the {openshift} CLI]. - -.Procedure -. Run the [command]`oc get nodes` command to identify the desired node. -The output will be similar to this: -+ -[subs="+quotes,attributes",options="nowrap"] ----- -$ oc get nodes -NAME STATUS ROLES AGE VERSION -crc-shdl4-master-0 Ready master,worker 7d7h v1.14.6+7e13ab9a7 ----- - -. Run [command]`oc debug nodes/__` where `__` is the name of the node printed in the previous step. diff --git a/modules/getting_started/partials/proc_installing.adoc b/modules/getting_started/partials/proc_installing.adoc deleted file mode 100644 index f13cc96..0000000 --- a/modules/getting_started/partials/proc_installing.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= Installing {prod} - -{prod} is available as a portable executable for {rhel}. -On {msw} and {mac}, {prod} is available using a guided installer. - -.Prerequisites -* Your host machine must meet the minimum system requirements. -For more information, see link:{crc-gsg-url}#minimum-system-requirements_gsg[Minimum system requirements]. - -.Procedure -. Download the link:{crc-download-url}[latest release of {prod}] for your platform. - -. On {msw}, extract the contents of the archive. - -. On {mac} or {msw}, run the guided installer and follow the instructions. -+ -[NOTE] -==== -On {msw}, you must install {prod} to your local [filename]*_C:\_* drive. -You cannot run {prod} from a network drive. -==== -+ -On {rhel}, assuming the archive is in the [filename]*_~/Downloads_* directory, follow these steps: -+ -.. Extract the contents of the archive: -+ -[subs="attributes"] ----- -$ cd ~/Downloads -$ tar xvf crc-linux-amd64.tar.xz ----- -+ -.. Create the [filename]*_~/bin_* directory if it does not exist and copy the [command]`{bin}` executable to it: -+ -[subs="attributes"] ----- -$ mkdir -p ~/bin -$ cp ~/Downloads/crc-linux-*-amd64/{bin} ~/bin ----- -+ -.. Add the [filename]*_~/bin_* directory to your `$PATH`: -+ -[subs="attributes"] ----- -$ export PATH=$PATH:$HOME/bin -$ echo 'export PATH=$PATH:$HOME/bin' >> ~/.bashrc ----- diff --git a/modules/getting_started/partials/proc_setting-up-remote-server.adoc b/modules/getting_started/partials/proc_setting-up-remote-server.adoc deleted file mode 100644 index d8cf47d..0000000 --- a/modules/getting_started/partials/proc_setting-up-remote-server.adoc +++ /dev/null @@ -1,95 +0,0 @@ -= Setting up {prod} on a remote server - -Configure a remote server to run an {ocp} cluster provided by {prod}. - -This procedure assumes the use of a {rhel}, {fed}, or {centos} server. -Run every command in this procedure on the remote server. - -[WARNING] -==== -**Perform this procedure only on a local network.** -Exposing an insecure server on the internet has many security implications. -==== - -.Prerequisites -* {prod} is installed and set up on the remote server. -For more information, see link:{crc-gsg-url}#installing_gsg[Installing {prod}] and link:{crc-gsg-url}#setting-up_gsg[Setting up {prod}]. -* {prod} is configured to use the {openshift} preset on the remote server. -For more information, see link:{crc-gsg-url}#changing-the-selected-preset_gsg[Changing the selected preset]. -* Your user account has `sudo` permissions on the remote server. - -.Procedure -. Start the cluster: -+ -[subs="+quotes,attributes"] ----- -$ {bin} start ----- -+ -Ensure that the cluster remains running during this procedure. - -. Install the [package]`haproxy` package and other utilities: -+ ----- -$ sudo dnf install haproxy /usr/sbin/semanage ----- - -. Modify the firewall to allow communication with the cluster: -+ ----- -$ sudo systemctl enable --now firewalld -$ sudo firewall-cmd --add-service=http --permanent -$ sudo firewall-cmd --add-service=https --permanent -$ sudo firewall-cmd --add-service=kube-apiserver --permanent -$ sudo firewall-cmd --reload ----- - -. For SELinux, allow HAProxy to listen on TCP port 6443 to serve `kube-apiserver` on this port: -+ ----- -$ sudo semanage port -a -t http_port_t -p tcp 6443 ----- - -. Create a backup of the default [application]`haproxy` configuration: -+ ----- -$ sudo cp /etc/haproxy/haproxy.cfg{,.bak} ----- - -. Configure [application]`haproxy` for use with the cluster: -+ -[subs="+quotes,attributes"] ----- -$ export CRC_IP=$({bin} ip) -$ sudo tee /etc/haproxy/haproxy.cfg &>/dev/null <__ -$ {bin} config set https-proxy http://proxy.example.com:____ -$ {bin} config set no-proxy ____ ----- - -. If the proxy uses a custom CA certificate file, set it as follows: -+ -[subs="+quotes,attributes"] ----- -$ {bin} config set proxy-ca-file ____ ----- - -[NOTE] -==== -Proxy-related values set in the configuration for {prod} have priority over values set with environment variables. -==== diff --git a/modules/getting_started/partials/proc_starting-monitoring.adoc b/modules/getting_started/partials/proc_starting-monitoring.adoc deleted file mode 100644 index e8759ac..0000000 --- a/modules/getting_started/partials/proc_starting-monitoring.adoc +++ /dev/null @@ -1,32 +0,0 @@ -= Starting monitoring - -{prod} disables cluster monitoring by default to ensure that {prod} can run on a typical notebook. -Monitoring is responsible for listing your cluster in the link:https://console.redhat.com/openshift[Red Hat Hybrid Cloud Console]. -Follow this procedure to enable monitoring for your cluster. - -.Prerequisites -* You must assign additional memory to the {prod} instance. -At least 14 GiB of memory, a value of `14336`, is recommended for core functionality. -Increased workloads will require more memory. -For more information, see link:{crc-gsg-url}#configuring-the-instance_gsg[Configuring the instance]. - -.Procedure -. Set the `enable-cluster-monitoring` configurable property to `true`: -+ -[subs="+quotes,attributes"] ----- -$ {bin} config set enable-cluster-monitoring true ----- - -. Start the instance: -+ -[subs="+quotes,attributes"] ----- -$ {bin} start ----- -+ -[WARNING] -==== -Cluster monitoring cannot be disabled. -To remove monitoring, set the `enable-cluster-monitoring` configurable property to `false` and delete the existing {prod} instance. -==== diff --git a/modules/getting_started/partials/proc_starting-the-instance.adoc b/modules/getting_started/partials/proc_starting-the-instance.adoc deleted file mode 100644 index 85dd2aa..0000000 --- a/modules/getting_started/partials/proc_starting-the-instance.adoc +++ /dev/null @@ -1,35 +0,0 @@ -= Starting the instance - -The [command]`{bin} start` command starts the {prod} instance and configured container runtime. - -.Prerequisites -* To avoid networking-related issues, ensure that you are not connected to a VPN and that your network connection is reliable. -* You set up the host machine using the [command]`{bin} setup` command. -For more information, see link:{crc-gsg-url}#setting-up_gsg[Setting up {prod}]. -* On {msw}, ensure that your user account can elevate to Administrator privileges. -* For the {openshift} preset, ensure that you have a valid {openshift} user pull secret. -Copy or download the pull secret from the Pull Secret section of the link:https://console.redhat.com/openshift/create/local[{prod} page on the {rh} Hybrid Cloud Console]. -+ -[NOTE] -==== -Accessing the user pull secret requires a Red Hat account. -==== - -.Procedure -. Start the {prod} instance: -+ -[subs="+quotes,attributes"] ----- -$ {bin} start ----- - -. For the {openshift} preset, supply your user pull secret when prompted. -+ -[NOTE] -==== -The cluster takes a minimum of four minutes to start the necessary containers and Operators before serving a request. -==== - -.Additional resources -* To change the default resources allocated to the instance, see link:{crc-gsg-url}#configuring-the-instance_gsg[Configuring the instance]. -* If you see errors during [command]`{bin} start`, see the link:{crc-gsg-url}#troubleshooting_gsg[Troubleshooting {prod}] section for potential solutions. diff --git a/modules/getting_started/partials/proc_stopping-the-instance.adoc b/modules/getting_started/partials/proc_stopping-the-instance.adoc deleted file mode 100644 index 30ee51a..0000000 --- a/modules/getting_started/partials/proc_stopping-the-instance.adoc +++ /dev/null @@ -1,12 +0,0 @@ -= Stopping the instance - -The [command]`{bin} stop` command stops the running {prod} instance and container runtime. -The stopping process takes a few minutes while the cluster shuts down. - -.Procedure -* Stop the {prod} instance and container runtime: -+ -[subs="+quotes,attributes"] ----- -$ {bin} stop ----- diff --git a/modules/getting_started/partials/proc_troubleshooting-bundle-version-mismatch.adoc b/modules/getting_started/partials/proc_troubleshooting-bundle-version-mismatch.adoc deleted file mode 100644 index 242e816..0000000 --- a/modules/getting_started/partials/proc_troubleshooting-bundle-version-mismatch.adoc +++ /dev/null @@ -1,19 +0,0 @@ -= Troubleshooting bundle version mismatch - -Created {prod} instances contain bundle information and instance data. -Bundle information and instance data is not updated when setting up a new {prod} release. -This information is not updated due to customization in the earlier instance data. -This will lead to errors when running the [command]`{bin} start` command: - -[subs="+quotes,attributes"] ----- -$ {bin} start -... -FATA Bundle 'crc_hyperkit_4.2.8.crcbundle' was requested, but the existing VM is using -'crc_hyperkit_4.2.2.crcbundle' ----- - -.Procedure -. Issue the [command]`{bin} delete` command before attempting to start the instance: -+ -include::partial$snip_crc-delete.adoc[] diff --git a/modules/getting_started/partials/proc_troubleshooting-expired-certificates.adoc b/modules/getting_started/partials/proc_troubleshooting-expired-certificates.adoc deleted file mode 100644 index bc9192d..0000000 --- a/modules/getting_started/partials/proc_troubleshooting-expired-certificates.adoc +++ /dev/null @@ -1,31 +0,0 @@ -= Troubleshooting expired certificates - -The system bundle of {ocp} in each released [command]`{bin}` executable expires 1 year after the release. -This expiration is due to certificates embedded in the {ocp} cluster. -The [command]`{bin} start` command triggers an automatic certificate renewal process when needed. -Certificate renewal can add up to five minutes to the start time of the cluster. - -To avoid this additional startup time, or in case of failures in the certificate renewal process, use the following procedure: - -.Procedure -To resolve expired certificate errors that cannot be automatically renewed: - -. link:{crc-download-url}[Download the latest {prod} release] and place the [command]`{bin}` executable in your `$PATH`. - -. Remove the cluster with certificate errors using the [command]`{bin} delete` command: -+ -include::partial$snip_crc-delete.adoc[] - -. Set up the new release: -+ -[subs="+quotes,attributes"] ----- -$ {bin} setup ----- - -. Start the new instance: -+ -[subs="+quotes,attributes"] ----- -$ {bin} start ----- diff --git a/modules/getting_started/partials/proc_troubleshooting-unknown-issues.adoc b/modules/getting_started/partials/proc_troubleshooting-unknown-issues.adoc deleted file mode 100644 index 5f22cdd..0000000 --- a/modules/getting_started/partials/proc_troubleshooting-unknown-issues.adoc +++ /dev/null @@ -1,64 +0,0 @@ -= Troubleshooting unknown issues - -Resolve most issues by restarting {prod} with a clean state. -This involves stopping the instance, deleting it, reverting changes made by the [command]`{bin} setup` command, reapplying those changes, and restarting the instance. - -.Prerequisites -* You set up the host machine with the [command]`{bin} setup` command. -For more information, see link:{crc-gsg-url}#setting-up_gsg[Setting up {prod}]. -* You started {prod} with the [command]`{bin} start` command. -For more information, see link:{crc-gsg-url}#starting-the-instance_gsg[Starting the instance]. -* You are using the latest {prod} release. -Using a version earlier than {prod} 1.2.0 might result in errors related to expired x509 certificates. -For more information, see link:{crc-gsg-url}#troubleshooting-expired-certificates_gsg[Troubleshooting expired certificates]. - -.Procedure -To troubleshoot {prod}, perform the following steps: - -. Stop the {prod} instance: -+ -[subs="+quotes,attributes"] ----- -$ {bin} stop ----- - -. Delete the {prod} instance: -+ -include::partial$snip_crc-delete.adoc[] - -. Clean up remaining changes from the [command]`{bin} setup` command: -+ -[subs="+quotes,attributes"] ----- -$ {bin} cleanup ----- -+ -[NOTE] -==== -The [command]`{bin} cleanup` command removes an existing {prod} instance and reverts changes to DNS entries created by the [command]`{bin} setup` command. -==== - -. Set up your host machine to reapply the changes: -+ -[subs="+quotes,attributes"] ----- -$ {bin} setup ----- - -. Start the {prod} instance: -+ -[subs="+quotes,attributes"] ----- -$ {bin} start ----- -+ -[NOTE] -==== -The cluster takes a minimum of four minutes to start the necessary containers and Operators before serving a request. -==== - -If your issue is not resolved by this procedure, perform the following steps: - -. link:https://github.com/crc-org/crc/issues[Search open issues] for the issue that you are encountering. -. If no existing issue addresses the encountered issue, link:https://github.com/crc-org/crc/issues/new[create an issue] and link:https://help.github.com/en/articles/file-attachments-on-issues-and-pull-requests[attach the [filename]*_~/.crc/crc.log_* file] to the created issue. -The [filename]*_~/.crc/crc.log_* file has detailed debugging and troubleshooting information which can help diagnose the problem that you are experiencing. diff --git a/modules/getting_started/partials/proc_upgrading.adoc b/modules/getting_started/partials/proc_upgrading.adoc deleted file mode 100644 index 89d2df4..0000000 --- a/modules/getting_started/partials/proc_upgrading.adoc +++ /dev/null @@ -1,32 +0,0 @@ -= Upgrading {prod} - -Newer versions of the {prod} executable require manual set up to prevent potential incompatibilities with earlier versions. - -.Procedure -. link:{crc-download-url}[Download the latest release of {prod}]. - -. Delete the existing {prod} instance: -+ -include::partial$snip_crc-delete.adoc[] - -. Replace the earlier [command]`{bin}` executable with the executable of the latest release. -Verify that the new [command]`{bin}` executable is in use by checking its version: -+ -[subs="+quotes,attributes"] ----- -$ {bin} version ----- - -. Set up the new {prod} release: -+ -[subs="+quotes,attributes"] ----- -$ {bin} setup ----- - -. Start the new {prod} instance: -+ -[subs="+quotes,attributes"] ----- -$ {bin} start ----- diff --git a/modules/getting_started/partials/proc_viewing-configuration.adoc b/modules/getting_started/partials/proc_viewing-configuration.adoc deleted file mode 100644 index 68a5fdc..0000000 --- a/modules/getting_started/partials/proc_viewing-configuration.adoc +++ /dev/null @@ -1,30 +0,0 @@ -= Viewing {prod} configuration - -The {prod} executable provides commands to view configurable properties and the current {prod} configuration. - -.Procedure -* To view the available configurable properties: -+ -[subs="+quotes,attributes"] ----- -$ {bin} config --help ----- - -* To view the values for a configurable property: -+ -[subs="+quotes,attributes"] ----- -$ {bin} config get __ ----- - -* To view the complete current configuration: -+ -[subs="+quotes,attributes"] ----- -$ {bin} config view ----- -+ -[NOTE] -==== -The [command]`{bin} config view` command does not return any information if the configuration consists of default values. -==== diff --git a/modules/getting_started/partials/ref_dns-configuration.adoc b/modules/getting_started/partials/ref_dns-configuration.adoc deleted file mode 100644 index 39ac05a..0000000 --- a/modules/getting_started/partials/ref_dns-configuration.adoc +++ /dev/null @@ -1,63 +0,0 @@ -= DNS configuration details - -== General DNS setup - -The {ocp} cluster managed by {prod} uses 2 DNS domain names, `crc.testing` and `apps-crc.testing`. -The `crc.testing` domain is for core {ocp} services. -The `apps-crc.testing` domain is for accessing {openshift} applications deployed on the cluster. - -For example, the {ocp} API server is exposed as `api.crc.testing` while the {ocp} console is accessed as `console-openshift-console.apps-crc.testing`. -These DNS domains are served by a `dnsmasq` DNS container running inside the {prod} instance. - -The [command]`{bin} setup` command detects and adjusts your system DNS configuration so that it can resolve these domains. -Additional checks are done to verify DNS is properly configured when running [command]`{bin} start`. - -== DNS on Linux - -On Linux, depending on your distribution, {prod} expects the following DNS configuration: - -=== NetworkManager + systemd-resolved - -This configuration is used by default on Fedora 33 or newer, and on Ubuntu Desktop editions. - -* {prod} expects NetworkManager to manage networking. -* {prod} configures `systemd-resolved` to forward requests for the `testing` domain to the `192.168.130.11` DNS server. -`192.168.130.11` is the IP of the {prod} instance. -* `systemd-resolved` configuration is done with a NetworkManager dispatcher script in [filename]*_/etc/NetworkManager/dispatcher.d/99-crc.sh_*: -+ ----- -#!/bin/sh - -export LC_ALL=C - -systemd-resolve --interface crc --set-dns 192.168.130.11 --set-domain ~testing - -exit 0 ----- - -[NOTE] -==== -`systemd-resolved` is also available as an unsupported Technology Preview on {rhel} and {centos} 8.3. -After {rhel-resolved-docs}[configuring the host] to use `systemd-resolved`, stop any running clusters and rerun [command]`{bin} setup`. -==== - -=== NetworkManager + dnsmasq - -This configuration is used by default on Fedora 32 or older, on {rhel}, and on {centos}. - -* {prod} expects NetworkManager to manage networking. -* NetworkManager uses `dnsmasq` with the [filename]*_/etc/NetworkManager/conf.d/crc-nm-dnsmasq.conf_* configuration file. -* The configuration file for this `dnsmasq` instance is [filename]*_/etc/NetworkManager/dnsmasq.d/crc.conf_*: -+ ----- -server=/crc.testing/192.168.130.11 -server=/apps-crc.testing/192.168.130.11 ----- - -** The NetworkManager `dnsmasq` instance forwards requests for the `crc.testing` and `apps-crc.testing` domains to the `192.168.130.11` DNS server. - -//// -== {msw} - -TODO -//// diff --git a/modules/getting_started/partials/ref_minimum-system-requirements.adoc b/modules/getting_started/partials/ref_minimum-system-requirements.adoc deleted file mode 100644 index c772803..0000000 --- a/modules/getting_started/partials/ref_minimum-system-requirements.adoc +++ /dev/null @@ -1,55 +0,0 @@ -= Minimum system requirements - -[role="_abstract"] -{prod} has the following minimum hardware and operating system requirements. - -== Hardware requirements - -{prod} is supported on these architectures: - -include::example$snip_{project-context}_preset_platforms.adoc[] - -{prod} does not support nested virtualization. - -Depending on the desired container runtime, {prod} requires the following system resources: - -=== For {ocp} - -* 4 physical CPU cores -* 10.5 GB of free memory -* 35 GB of storage space - -=== For {ushift} - -* 2 physical CPU cores -* 4 GB of free memory -* 35 GB of storage space - -[NOTE] -==== -The {ocp} and {ushift} presets require these minimum resources to run in the {prod} instance. -Some workloads might require more resources. -To assign more resources to the {prod} instance, see link:{crc-gsg-url}#configuring-the-instance_gsg[Configuring the instance]. -==== - -== Operating system requirements - -{prod} requires the following minimum version of a supported operating system: - -=== Requirements on {msw} - -* On {msw}, {prod} requires fully updated {msw} 10 or {msw} 11. -{prod} does not work on earlier versions of {msw}. -* {prod} does not work on {msw} Home Edition. - -=== Requirements on {mac} - -* On {mac}, {prod} requires {mac} 13 Ventura or later. -{prod} does not work on earlier versions of {mac}. - -=== Requirements on Linux - -* On Linux, {prod} is supported only on the latest two {rhel}/{centos} 8 and 9 minor releases and on the latest two stable {fed} releases. -* When using {rhel}, the machine running {prod} must be link:https://access.redhat.com/solutions/253273[registered with the Red Hat Customer Portal]. -* {ubuntu} 18.04 LTS or later and {debian} 10 or later are not supported and might require manual set up of the host machine. -* See link:{crc-gsg-url}#required-software-packages_gsg[Required software packages] to install the required packages for your Linux distribution. diff --git a/modules/getting_started/partials/ref_required-software-packages.adoc b/modules/getting_started/partials/ref_required-software-packages.adoc deleted file mode 100644 index e76ca2b..0000000 --- a/modules/getting_started/partials/ref_required-software-packages.adoc +++ /dev/null @@ -1,12 +0,0 @@ -= Required software packages for Linux - -{prod} requires the `libvirt` and `NetworkManager` packages to run on Linux. -Consult the following table to find the command used to install these packages for your Linux distribution: - -.Package installation commands by distribution -[options="header"] -|==== -|Linux Distribution|Installation command -|{fed}/{rhel}/{centos}|`sudo dnf install NetworkManager` -|{debian}/{ubuntu}|`sudo apt install qemu-kvm libvirt-daemon libvirt-daemon-system network-manager` -|==== diff --git a/modules/getting_started/partials/ref_reserved-ip-subnets.adoc b/modules/getting_started/partials/ref_reserved-ip-subnets.adoc deleted file mode 100644 index 8dceed0..0000000 --- a/modules/getting_started/partials/ref_reserved-ip-subnets.adoc +++ /dev/null @@ -1,13 +0,0 @@ -= Reserved IP subnets - -The {ocp} cluster managed by {prod} reserves IP subnets for internal use, which should not collide with your host network. -Ensure that the following IP subnets are available for use: - -.Reserved IP subnets -* `10.217.0.0/22` -* `10.217.4.0/23` -* `192.168.126.0/24` - -Additionally, the host hypervisor might reserve another IP subnet depending on the host operating system. -No additional subnet is reserved on {mac} and {msw}. -The additional reserved subnet for Linux is `192.168.130.0/24`. diff --git a/modules/getting_started/partials/snip_crc-delete.adoc b/modules/getting_started/partials/snip_crc-delete.adoc deleted file mode 100644 index ee426f0..0000000 --- a/modules/getting_started/partials/snip_crc-delete.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[subs="+quotes,attributes"] ----- -$ {bin} delete ----- -+ -[WARNING] -==== -The [command]`{bin} delete` command results in the loss of data stored in the {prod} instance. -Save any desired information stored in the instance before running this command. -====