From 16ec211a17a307725f962b8fb9b1a049581806c3 Mon Sep 17 00:00:00 2001 From: Gerard Braad Date: Fri, 29 Nov 2024 06:53:22 +0000 Subject: [PATCH] Initial commit --- .github/workflows/publish-docs.yml | 27 ++++++ .htmltest.yml | 10 ++ .vale.ini | 14 +++ Containerfile | 11 +++ Makefile | 20 ++++ OWNERS | 7 ++ README.md | 16 +++- antora-playbook.yml | 69 ++++++++++++++ antora.yml | 7 ++ extensions/get-versions.js | 46 +++++++++ .../examples/snip_crc_preset_list.adoc | 3 + .../examples/snip_crc_preset_names.adoc | 8 ++ .../examples/snip_crc_preset_platforms.adoc | 8 ++ modules/getting_started/nav.adoc | 10 ++ .../pages/administrative-tasks.adoc | 8 ++ .../getting_started/pages/configuring.adoc | 12 +++ modules/getting_started/pages/installing.adoc | 16 ++++ .../getting_started/pages/introducing.adoc | 8 ++ modules/getting_started/pages/networking.adoc | 16 ++++ .../pages/troubleshooting.adoc | 19 ++++ modules/getting_started/pages/using.adoc | 16 ++++ ...embly_accessing-the-openshift-cluster.adoc | 9 ++ .../partials/con_about-configuration.adoc | 11 +++ .../partials/con_about-presets.adoc | 17 ++++ .../con_about-usage-data-collection.adoc | 10 ++ .../getting_started/partials/con_about.adoc | 10 ++ ...ces-from-production-openshift-install.adoc | 24 +++++ ...ssing-the-internal-openshift-registry.adoc | 70 ++++++++++++++ ...cessing-the-openshift-cluster-with-oc.adoc | 53 +++++++++++ ...c_accessing-the-openshift-web-console.adoc | 34 +++++++ .../proc_changing-the-selected-preset.adoc | 29 ++++++ .../proc_configuring-the-instance.adoc | 52 ++++++++++ ...roc_configuring-usage-data-collection.adoc | 28 ++++++ .../partials/proc_connecting-to-host.adoc | 35 +++++++ .../proc_connecting-to-remote-instance.adoc | 63 ++++++++++++ .../partials/proc_deleting-the-instance.adoc | 8 ++ ...deploying-sample-application-with-odo.adoc | 78 +++++++++++++++ .../proc_enabling-override-operators.adoc | 34 +++++++ ...shell-access-to-the-openshift-cluster.adoc | 25 +++++ .../partials/proc_installing.adoc | 47 +++++++++ .../proc_setting-up-remote-server.adoc | 95 +++++++++++++++++++ .../partials/proc_setting-up.adoc | 33 +++++++ .../partials/proc_starting-behind-proxy.adoc | 35 +++++++ .../partials/proc_starting-monitoring.adoc | 32 +++++++ .../partials/proc_starting-the-instance.adoc | 35 +++++++ .../partials/proc_stopping-the-instance.adoc | 12 +++ ...oubleshooting-bundle-version-mismatch.adoc | 19 ++++ ..._troubleshooting-expired-certificates.adoc | 31 ++++++ .../proc_troubleshooting-unknown-issues.adoc | 64 +++++++++++++ .../partials/proc_upgrading.adoc | 32 +++++++ .../partials/proc_viewing-configuration.adoc | 30 ++++++ .../partials/ref_dns-configuration.adoc | 63 ++++++++++++ .../ref_minimum-system-requirements.adoc | 55 +++++++++++ .../ref_required-software-packages.adoc | 12 +++ .../partials/ref_reserved-ip-subnets.adoc | 13 +++ .../partials/snip_crc-delete.adoc | 10 ++ supplemental-ui/partials/article-404.hbs | 14 +++ supplemental-ui/partials/header-content.hbs | 27 ++++++ 58 files changed, 1599 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/publish-docs.yml create mode 100644 .htmltest.yml create mode 100644 .vale.ini create mode 100644 Containerfile create mode 100644 Makefile create mode 100644 OWNERS create mode 100644 antora-playbook.yml create mode 100644 antora.yml create mode 100644 extensions/get-versions.js create mode 100644 modules/getting_started/examples/snip_crc_preset_list.adoc create mode 100644 modules/getting_started/examples/snip_crc_preset_names.adoc create mode 100644 modules/getting_started/examples/snip_crc_preset_platforms.adoc create mode 100644 modules/getting_started/nav.adoc create mode 100644 modules/getting_started/pages/administrative-tasks.adoc create mode 100644 modules/getting_started/pages/configuring.adoc create mode 100644 modules/getting_started/pages/installing.adoc create mode 100644 modules/getting_started/pages/introducing.adoc create mode 100644 modules/getting_started/pages/networking.adoc create mode 100644 modules/getting_started/pages/troubleshooting.adoc create mode 100644 modules/getting_started/pages/using.adoc create mode 100644 modules/getting_started/partials/assembly_accessing-the-openshift-cluster.adoc create mode 100644 modules/getting_started/partials/con_about-configuration.adoc create mode 100644 modules/getting_started/partials/con_about-presets.adoc create mode 100644 modules/getting_started/partials/con_about-usage-data-collection.adoc create mode 100644 modules/getting_started/partials/con_about.adoc create mode 100644 modules/getting_started/partials/con_differences-from-production-openshift-install.adoc create mode 100644 modules/getting_started/partials/proc_accessing-the-internal-openshift-registry.adoc create mode 100644 modules/getting_started/partials/proc_accessing-the-openshift-cluster-with-oc.adoc create mode 100644 modules/getting_started/partials/proc_accessing-the-openshift-web-console.adoc create mode 100644 modules/getting_started/partials/proc_changing-the-selected-preset.adoc create mode 100644 modules/getting_started/partials/proc_configuring-the-instance.adoc create mode 100644 modules/getting_started/partials/proc_configuring-usage-data-collection.adoc create mode 100644 modules/getting_started/partials/proc_connecting-to-host.adoc create mode 100644 modules/getting_started/partials/proc_connecting-to-remote-instance.adoc create mode 100644 modules/getting_started/partials/proc_deleting-the-instance.adoc create mode 100644 modules/getting_started/partials/proc_deploying-sample-application-with-odo.adoc create mode 100644 modules/getting_started/partials/proc_enabling-override-operators.adoc create mode 100644 modules/getting_started/partials/proc_getting-shell-access-to-the-openshift-cluster.adoc create mode 100644 modules/getting_started/partials/proc_installing.adoc create mode 100644 modules/getting_started/partials/proc_setting-up-remote-server.adoc create mode 100644 modules/getting_started/partials/proc_setting-up.adoc create mode 100644 modules/getting_started/partials/proc_starting-behind-proxy.adoc create mode 100644 modules/getting_started/partials/proc_starting-monitoring.adoc create mode 100644 modules/getting_started/partials/proc_starting-the-instance.adoc create mode 100644 modules/getting_started/partials/proc_stopping-the-instance.adoc create mode 100644 modules/getting_started/partials/proc_troubleshooting-bundle-version-mismatch.adoc create mode 100644 modules/getting_started/partials/proc_troubleshooting-expired-certificates.adoc create mode 100644 modules/getting_started/partials/proc_troubleshooting-unknown-issues.adoc create mode 100644 modules/getting_started/partials/proc_upgrading.adoc create mode 100644 modules/getting_started/partials/proc_viewing-configuration.adoc create mode 100644 modules/getting_started/partials/ref_dns-configuration.adoc create mode 100644 modules/getting_started/partials/ref_minimum-system-requirements.adoc create mode 100644 modules/getting_started/partials/ref_required-software-packages.adoc create mode 100644 modules/getting_started/partials/ref_reserved-ip-subnets.adoc create mode 100644 modules/getting_started/partials/snip_crc-delete.adoc create mode 100644 supplemental-ui/partials/article-404.hbs create mode 100644 supplemental-ui/partials/header-content.hbs diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml new file mode 100644 index 0000000..49ad624 --- /dev/null +++ b/.github/workflows/publish-docs.yml @@ -0,0 +1,27 @@ +name: Build and publish docs +on: + push: + branches: + - "main" + pull_request: {} +jobs: + build: + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: + - ubuntu-latest + steps: + - name: Check out repository code + uses: actions/checkout@v4 + - name: Build docs + run: CONTAINER_RUNTIME=docker make build_docs + - name: Check links in docs + run: CONTAINER_RUNTIME=docker make docs_check_links + - name: Deploy + uses: peaceiris/actions-gh-pages@v4 + if: github.ref == 'refs/heads/main' + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./public diff --git a/.htmltest.yml b/.htmltest.yml new file mode 100644 index 0000000..1f22ccc --- /dev/null +++ b/.htmltest.yml @@ -0,0 +1,10 @@ +--- +# Configuration file for htmltest +# See: https://github.com/wjdp/htmltest + +DirectoryPath: docs/build +OutputDir: .cache/htmltest +CacheExpires: "12h" # Default is 2 weeks. +ExternalTimeout: 60 # (seconds) default is 15. +IgnoreURLs: + - https://crc.dev/crc diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 0000000..0ae996d --- /dev/null +++ b/.vale.ini @@ -0,0 +1,14 @@ +# Vale configuration file for `che-docs` repository. +# See: https://docs.errata.ai/vale/config + +StylesPath = .cache/vale +Packages = RedHat +MinAlertLevel = warning + +[*.adoc] +BasedOnStyles = RedHat +RedHat.Annotations = suggestion +RedHat.Headings = suggestion +RedHat.Slash = warning +RedHat.Usage = suggestion +RedHat.Spelling = suggestion diff --git a/Containerfile b/Containerfile new file mode 100644 index 0000000..da7dc61 --- /dev/null +++ b/Containerfile @@ -0,0 +1,11 @@ +FROM docker.io/antora/antora +LABEL org.opencontainers.image.source="https://github.com/crc-org/crc" +RUN yarn global add --ignore-optional --silent \ + @antora/atlas-extension \ + @antora/cli \ + @antora/collector-extension \ + @antora/lunr-extension \ + @antora/pdf-extension \ + @antora/site-generator \ + asciidoctor-kroki +RUN antora --version diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..b17ea9f --- /dev/null +++ b/Makefile @@ -0,0 +1,20 @@ +SHELL := /bin/bash -o pipefail + +# Docs build related variables +DOCS_BUILD_DIR ?= public +DOCS_BUILD_CONTAINER ?= quay.io/crcont/antora:latest +DOCS_SERVE_CONTAINER ?= docker.io/httpd:alpine +DOCS_TEST_CONTAINER ?= docker.io/wjdp/htmltest:latest +DOCS_BUILD_TARGET ?= ./source/getting_started/master.adoc + +.PHONY: build_docs +build_docs: + ${CONTAINER_RUNTIME} run -v $(CURDIR):/antora$(SELINUX_VOLUME_LABEL) --rm $(DOCS_BUILD_CONTAINER) --stacktrace antora-playbook.yml + +.PHONY: docs_serve +docs_serve: build_docs + ${CONTAINER_RUNTIME} run -it -v $(CURDIR)/$(DOCS_BUILD_DIR):/usr/local/apache2/htdocs/$(SELINUX_VOLUME_LABEL) --rm -p 8088:80/tcp $(DOCS_SERVE_CONTAINER) + +.PHONY: docs_check_links +docs_check_links: + ${CONTAINER_RUNTIME} run -v $(CURDIR):/test$(SELINUX_VOLUME_LABEL) --rm $(DOCS_TEST_CONTAINER) -c .htmltest.yml diff --git a/OWNERS b/OWNERS new file mode 100644 index 0000000..9a0af26 --- /dev/null +++ b/OWNERS @@ -0,0 +1,7 @@ +# See the OWNERS docs: https://git.k8s.io/community/contributors/guide/owners.md +# This file just uses aliases defined in OWNERS_ALIASES. + +approvers: + - crc-approvers +reviewers: + - doc-reviewers diff --git a/README.md b/README.md index 8859ea8..5a5500b 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,16 @@ -# docs CRC User documentation; Getting Started Guide +============================================= + + +## Prerequisites +* A container engine, such as Podman or Docker. + +## Procedure + +* Build and serve the documentation: + +```shell +$ make docs_serve +``` + +The documentation will be available locally at http://localhost:8088/. diff --git a/antora-playbook.yml b/antora-playbook.yml new file mode 100644 index 0000000..532a549 --- /dev/null +++ b/antora-playbook.yml @@ -0,0 +1,69 @@ +--- +site: + title: CRC Documentation + start_page: getting_started:getting_started:introducing.adoc + url: https://crc.dev/docs + robots: allow +content: + sources: + - url: ./ # Point to Git repository + branches: HEAD # Use local conntent + edit_url: "https://github.com/crc-org/crc/edit/main/{path}" + start_path: docs # Point to docs content +output: + clean: true # Delete stale content + dir: public +runtime: + cache_dir: .cache/antora # Use a local directory rather than $HOME + log: + failure_level: warn # Fail on missing attributes + level: debug # Extra verbose +ui: + bundle: + url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable + snapshot: true + supplemental_files: ./supplemental-ui +urls: + html_extension_style: indexify + redirect_facility: static +antora: + extensions: + - "@antora/lunr-extension" + - ./extensions/get-versions.js +asciidoc: + sourcemap: true + attributes: + icons: font + nbsp: " " + project-context: crc + # Platforms + rh: "Red{nbsp}Hat" + rhel: "Red{nbsp}Hat Enterprise{nbsp}Linux" + fed: Fedora + centos: CentOS + mac: macOS + msw: Microsoft Windows + debian: Debian + ubuntu: Ubuntu + openshift: OpenShift + ocp: OpenShift Container Platform + okd: OKD + ushift: MicroShift + # Product naming + prod: CRC + rh-prod: CRC + 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" + oc-download-url: https://mirror.openshift.com/pub/openshift-v4/clients/ocp/latest/ + odo-docs-url: https://odo.dev/docs/introduction + odo-docs-url-installing: https://odo.dev/docs/overview/installation + telemetry-notice-url: https://developers.redhat.com/article/tool-data-collection + rhel-resolved-docs: https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/configuring_and_managing_networking/using-different-dns-servers-for-different-domains_configuring-and-managing-networking diff --git a/antora.yml b/antora.yml new file mode 100644 index 0000000..47163df --- /dev/null +++ b/antora.yml @@ -0,0 +1,7 @@ +--- +name: getting_started +title: Getting started with CRC +version: ~ # Unversioned component version +start_page: getting_started:introducing.adoc +nav: + - modules/getting_started/nav.adoc diff --git a/extensions/get-versions.js b/extensions/get-versions.js new file mode 100644 index 0000000..c7d3ab8 --- /dev/null +++ b/extensions/get-versions.js @@ -0,0 +1,46 @@ +"use strict"; +const fs = require("fs"); +const child_process = require("child_process"); +module.exports.register = function () { + this.on("playbookBuilt", function ({ playbook }) { + // Get versions from Makefile + // Use utf8 encoding to have a string rather than a buffer in the output + const ocp_ver_full = child_process.execSync( + "grep '^OPENSHIFT_VERSION' Makefile | cut -d' ' -f3 | tr -d '\n'", + { encoding: "utf8" } + ); + const ocp_ver = child_process.execSync( + "grep '^OPENSHIFT_VERSION' Makefile | cut -d' ' -f3 | cut -d'.' -f-2 | tr -d '\n'", + { encoding: "utf8" } + ); + const prod_ver_full = child_process.execSync( + "grep '^CRC_VERSION' Makefile | cut -d' ' -f3 | tr -d '\n'", + { encoding: "utf8" } + ); + const prod_ver = child_process.execSync( + "grep '^CRC_VERSION' Makefile | cut -d' ' -f3 | cut -d'.' -f-2 | tr -d '\n'", + { encoding: "utf8" } + ); + const ushift_ver = child_process.execSync( + "grep '^MICROSHIFT_VERSION' Makefile | cut -d' ' -f3 | tr -d '\n'", + { encoding: "utf8" } + ); + + // Display versions + console.log("OpenShift patch version: " + ocp_ver_full); + console.log("OpenShift minor version: " + ocp_ver); + console.log("CRC patch version: " + prod_ver_full); + console.log("CRC minor version: " + prod_ver); + console.log("MicroShift version: " + ushift_ver); + + // Set attributes values + Object.assign(playbook.asciidoc.attributes, { + "ocp-ver": ocp_ver, + "ocp-ver-full": ocp_ver_full, + "prod-ver": prod_ver, + "prod-ver-full": prod_ver_full, + "ushift-ver": ushift_ver, + }); + this.updateVariables({ playbook }); + }); +}; diff --git a/modules/getting_started/examples/snip_crc_preset_list.adoc b/modules/getting_started/examples/snip_crc_preset_list.adoc new file mode 100644 index 0000000..1ea5c6f --- /dev/null +++ b/modules/getting_started/examples/snip_crc_preset_list.adoc @@ -0,0 +1,3 @@ +`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 new file mode 100644 index 0000000..332bebb --- /dev/null +++ b/modules/getting_started/examples/snip_crc_preset_names.adoc @@ -0,0 +1,8 @@ +.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 new file mode 100644 index 0000000..24898b5 --- /dev/null +++ b/modules/getting_started/examples/snip_crc_preset_platforms.adoc @@ -0,0 +1,8 @@ +.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/nav.adoc b/modules/getting_started/nav.adoc new file mode 100644 index 0000000..0ebb37f --- /dev/null +++ b/modules/getting_started/nav.adoc @@ -0,0 +1,10 @@ += Getting Started Guide + +* xref:introducing.adoc[] +* xref:installing.adoc[] +* xref:using.adoc[] +* xref:configuring.adoc[] +* xref:networking.adoc[] +* xref:administrative-tasks.adoc[] +* xref:troubleshooting.adoc[] + diff --git a/modules/getting_started/pages/administrative-tasks.adoc b/modules/getting_started/pages/administrative-tasks.adoc new file mode 100644 index 0000000..b6105e3 --- /dev/null +++ b/modules/getting_started/pages/administrative-tasks.adoc @@ -0,0 +1,8 @@ +: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 new file mode 100644 index 0000000..a39165c --- /dev/null +++ b/modules/getting_started/pages/configuring.adoc @@ -0,0 +1,12 @@ +: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 new file mode 100644 index 0000000..2f3f824 --- /dev/null +++ b/modules/getting_started/pages/installing.adoc @@ -0,0 +1,16 @@ +: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 new file mode 100644 index 0000000..cbfc4ef --- /dev/null +++ b/modules/getting_started/pages/introducing.adoc @@ -0,0 +1,8 @@ +: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 new file mode 100644 index 0000000..d92f1ea --- /dev/null +++ b/modules/getting_started/pages/networking.adoc @@ -0,0 +1,16 @@ +: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 new file mode 100644 index 0000000..3134229 --- /dev/null +++ b/modules/getting_started/pages/troubleshooting.adoc @@ -0,0 +1,19 @@ +: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 new file mode 100644 index 0000000..1c018e8 --- /dev/null +++ b/modules/getting_started/pages/using.adoc @@ -0,0 +1,16 @@ +[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 new file mode 100644 index 0000000..6fe9592 --- /dev/null +++ b/modules/getting_started/partials/assembly_accessing-the-openshift-cluster.adoc @@ -0,0 +1,9 @@ += 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 new file mode 100644 index 0000000..f5cf8c4 --- /dev/null +++ b/modules/getting_started/partials/con_about-configuration.adoc @@ -0,0 +1,11 @@ += 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 new file mode 100644 index 0000000..8698302 --- /dev/null +++ b/modules/getting_started/partials/con_about-presets.adoc @@ -0,0 +1,17 @@ += 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 new file mode 100644 index 0000000..953fb52 --- /dev/null +++ b/modules/getting_started/partials/con_about-usage-data-collection.adoc @@ -0,0 +1,10 @@ += 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 new file mode 100644 index 0000000..b3e983c --- /dev/null +++ b/modules/getting_started/partials/con_about.adoc @@ -0,0 +1,10 @@ += 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/con_differences-from-production-openshift-install.adoc b/modules/getting_started/partials/con_differences-from-production-openshift-install.adoc new file mode 100644 index 0000000..d3ffa65 --- /dev/null +++ b/modules/getting_started/partials/con_differences-from-production-openshift-install.adoc @@ -0,0 +1,24 @@ += Differences from a production {ocp} installation + +The {openshift} preset for {rh-prod} provides a regular {ocp} installation with the following notable differences: + +* **The {ocp} cluster is ephemeral and is not intended for production use.** +* **{prod} does not have a supported upgrade path to newer {ocp} versions.** +Upgrading the {ocp} version might cause issues that are difficult to reproduce. +* It uses a single node, which behaves as both a control plane and worker node. +* It disables the Cluster Monitoring Operator by default. +This disabled Operator causes the corresponding part of the web console to be non-functional. +* It disables the following operators: +** Cloud Credential Operator. +** Cluster Autoscaler Operator. +** Cloud Controller Manager Operator. +* The {ocp} cluster runs in a virtual machine known as an __instance__. +This might cause other differences, particularly with external networking. + +The {ocp} cluster provided by {prod} also includes the following non-customizable cluster settings. +These settings should not be modified: + +* The ***.crc.testing** domain. +* The address range used for internal cluster communication. +** The cluster uses the **172** address range. +This can cause issues when, for example, a proxy is run in the same address space. 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 new file mode 100644 index 0000000..b9caa05 --- /dev/null +++ b/modules/getting_started/partials/proc_accessing-the-internal-openshift-registry.adoc @@ -0,0 +1,70 @@ += 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 new file mode 100644 index 0000000..53f12f6 --- /dev/null +++ b/modules/getting_started/partials/proc_accessing-the-openshift-cluster-with-oc.adoc @@ -0,0 +1,53 @@ += 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 new file mode 100644 index 0000000..bd950df --- /dev/null +++ b/modules/getting_started/partials/proc_accessing-the-openshift-web-console.adoc @@ -0,0 +1,34 @@ += 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 new file mode 100644 index 0000000..308fd4f --- /dev/null +++ b/modules/getting_started/partials/proc_changing-the-selected-preset.adoc @@ -0,0 +1,29 @@ += 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 new file mode 100644 index 0000000..6035d1b --- /dev/null +++ b/modules/getting_started/partials/proc_configuring-the-instance.adoc @@ -0,0 +1,52 @@ += 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 new file mode 100644 index 0000000..b83f021 --- /dev/null +++ b/modules/getting_started/partials/proc_configuring-usage-data-collection.adoc @@ -0,0 +1,28 @@ += 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 new file mode 100644 index 0000000..feed0d7 --- /dev/null +++ b/modules/getting_started/partials/proc_connecting-to-host.adoc @@ -0,0 +1,35 @@ += 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 new file mode 100644 index 0000000..02e45fe --- /dev/null +++ b/modules/getting_started/partials/proc_connecting-to-remote-instance.adoc @@ -0,0 +1,63 @@ += 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 new file mode 100644 index 0000000..88e8f4a --- /dev/null +++ b/modules/getting_started/partials/proc_getting-shell-access-to-the-openshift-cluster.adoc @@ -0,0 +1,25 @@ += 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 new file mode 100644 index 0000000..f13cc96 --- /dev/null +++ b/modules/getting_started/partials/proc_installing.adoc @@ -0,0 +1,47 @@ += 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 new file mode 100644 index 0000000..d8cf47d --- /dev/null +++ b/modules/getting_started/partials/proc_setting-up-remote-server.adoc @@ -0,0 +1,95 @@ += 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 new file mode 100644 index 0000000..e8759ac --- /dev/null +++ b/modules/getting_started/partials/proc_starting-monitoring.adoc @@ -0,0 +1,32 @@ += 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 new file mode 100644 index 0000000..85dd2aa --- /dev/null +++ b/modules/getting_started/partials/proc_starting-the-instance.adoc @@ -0,0 +1,35 @@ += 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 new file mode 100644 index 0000000..30ee51a --- /dev/null +++ b/modules/getting_started/partials/proc_stopping-the-instance.adoc @@ -0,0 +1,12 @@ += 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 new file mode 100644 index 0000000..242e816 --- /dev/null +++ b/modules/getting_started/partials/proc_troubleshooting-bundle-version-mismatch.adoc @@ -0,0 +1,19 @@ += 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 new file mode 100644 index 0000000..bc9192d --- /dev/null +++ b/modules/getting_started/partials/proc_troubleshooting-expired-certificates.adoc @@ -0,0 +1,31 @@ += 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 new file mode 100644 index 0000000..5f22cdd --- /dev/null +++ b/modules/getting_started/partials/proc_troubleshooting-unknown-issues.adoc @@ -0,0 +1,64 @@ += 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 new file mode 100644 index 0000000..89d2df4 --- /dev/null +++ b/modules/getting_started/partials/proc_upgrading.adoc @@ -0,0 +1,32 @@ += 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 new file mode 100644 index 0000000..68a5fdc --- /dev/null +++ b/modules/getting_started/partials/proc_viewing-configuration.adoc @@ -0,0 +1,30 @@ += 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 new file mode 100644 index 0000000..39ac05a --- /dev/null +++ b/modules/getting_started/partials/ref_dns-configuration.adoc @@ -0,0 +1,63 @@ += 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 new file mode 100644 index 0000000..c772803 --- /dev/null +++ b/modules/getting_started/partials/ref_minimum-system-requirements.adoc @@ -0,0 +1,55 @@ += 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 new file mode 100644 index 0000000..e76ca2b --- /dev/null +++ b/modules/getting_started/partials/ref_required-software-packages.adoc @@ -0,0 +1,12 @@ += 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 new file mode 100644 index 0000000..8dceed0 --- /dev/null +++ b/modules/getting_started/partials/ref_reserved-ip-subnets.adoc @@ -0,0 +1,13 @@ += 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 new file mode 100644 index 0000000..ee426f0 --- /dev/null +++ b/modules/getting_started/partials/snip_crc-delete.adoc @@ -0,0 +1,10 @@ +[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. +==== diff --git a/supplemental-ui/partials/article-404.hbs b/supplemental-ui/partials/article-404.hbs new file mode 100644 index 0000000..8e8d344 --- /dev/null +++ b/supplemental-ui/partials/article-404.hbs @@ -0,0 +1,14 @@ +
+

{{{or page.title "Page Not Found"}}}

+
+

The page you’re looking for does not exist. It may have been moved. + You can return to the + start page, or follow one of the + links in the navigation to the left.

+
+
+

If you arrived on this page by clicking on a link, please notify the + owner of the site that the link is broken. If you typed the URL of this + page manually, please double check that you entered the address correctly.

+
+
diff --git a/supplemental-ui/partials/header-content.hbs b/supplemental-ui/partials/header-content.hbs new file mode 100644 index 0000000..7f676fa --- /dev/null +++ b/supplemental-ui/partials/header-content.hbs @@ -0,0 +1,27 @@ +
+ + +