-
Notifications
You must be signed in to change notification settings - Fork 24
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[DOC] Update README, add index and installation process (#408)
Signed-off-by: Daniel Villanueva <[email protected]>
- Loading branch information
1 parent
7e7eced
commit bf1b8c6
Showing
1 changed file
with
94 additions
and
68 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,127 +1,153 @@ | ||
| # Red Hat OpenShift Local extension | ||
|
|
||
| Integration for [Red Hat OpenShift Local][product page] clusters. It will help you install and set up the environment. and allows you to control the lifecycle and configuration from [Podman Desktop][podman-desktop]. | ||
| Integration for [Red Hat OpenShift Local][product page] clusters. It will help you install and set up the environment, and allows you to control the lifecycle and configuration from [Podman Desktop][podman-desktop]. Some of the features available in the extension include: | ||
| * Start/Stop/Restart/Delete OpenShift Local clusters | ||
| * Change the OpenShift Local cluster preset | ||
| * Update the OpenShift Local version | ||
|
|
||
| ## Index | ||
| - [Installation](#installation) | ||
| - [Requirements](#requirements) | ||
| - [Extension installation](#extension-installation) | ||
| - [OpenShift Local installation](#openshift-local-installation) | ||
| - [Usage](#usage) | ||
| - [Deployment to OpenShift Local](#deployment-to-openshift-local) | ||
|
|
||
| ## Usage | ||
| ## Installation | ||
|
|
||
| Once installed you can configure parameters used to create OpenShift Local Cluster in extension's settings page. | ||
| ### Requirements | ||
|
|
||
| You need to have a working [Podman Desktop][podman-desktop] installation. | ||
| Each preset of OpenShift Local has their own requirements, please check the [documentation][documentation page] for more information. | ||
|
|
||
|  | ||
|
|
||
| To create new OpenShift Local Cluster switch to `Resources` Settings page and press `Create new ...` button. | ||
| #### Preset types | ||
| * **Microshift (experimental)** | ||
| Provides a lightweight and optimized environment with a limited set of services. | ||
| * **OpenShift** | ||
| Provides a single node OpenShift cluster with a fuller set of services, including a web console (requires more resources). | ||
|
|
||
|  | ||
|
|
||
| When new cluser has created there should be new connection visible in **OpenShift Local** section. | ||
| #### Pull-secret | ||
| To pull container images from the registry, a pull secret is necessary. You can get a pull secret by navigating to the dashboard and clicking the **Obtain pull-secret** or opening the [Red Hat OpenShift Local download page][download page] in your browser. | ||
|
|
||
|  | ||
| ### Extension installation | ||
|
|
||
| There is also system tray menu for OpenShift Local where you can run cluster related commands. | ||
| 1. Open Podman Desktop. | ||
| 2. Go to the **Extensions** page: | ||
|  | ||
| 3. Now you have two options: | ||
| 1. Switch to the **Catalog** tab and click on the `Install` icon in the `Red Hat OpenShift Local` extension item: | ||
|  | ||
| 2. Or click on the `Install custom...` button on the upper right corner, enter `ghcr.io/crc-org/crc-extension` in the `OCI Image` field, and click on `Install`: | ||
|
|
||
|  | ||
|  | ||
|
|
||
| To deploy your first application to OpenShift Local pull `httpd-24` image from public Red Hat image registry using **Pull an Image** page. Open **Images** page using activity bar and press `Pull` button in upper right corner. | ||
| This second approach is useful to get older versions or development releases. | ||
|
|
||
|  | ||
| ### OpenShift Local installation | ||
| If you don't have OpenShift Local installed in your system already, Podman Desktop can handle it for you. | ||
|
|
||
| Paste `registry.access.redhat.com/ubi8/httpd-24` into `Image to pull` field and press `Pull Image` button. | ||
| Go to the `Dashboard` page, and in the `OpenShift Local` section you will find the `NOT-INSTALLED` label. Click on the `Install` button: | ||
|
|
||
|  | ||
|  | ||
|
|
||
| After the image sucessfully pulled from the registry press `Done` button to navigate back to **Images** page. | ||
| A dialog will appear, click on the `Yes` button: | ||
|
|
||
|  | ||
|  | ||
|
|
||
| Request context menu for `httpd-24` image you just pulled by clicking on right most button in the row. Then select `Push image to OpenShift Local cluster` menu item. | ||
| Follow the OpenShift Local installation wizard, picking the options that suit your needs: | ||
|
|
||
|  | ||
|  | ||
|
|
||
| Th progress for `Push` command it available in Podman Desktop **Tasks** View. | ||
| You can check the progress on the download of the binaries on the bottom of the interface: | ||
|
|
||
|  | ||
|  | ||
|
|
||
| When `Push` command is done the image is ready to be deployed to OpenShift Local cluster. First start a local container from the image using `Run` button. | ||
| ## Usage | ||
|
|
||
|  | ||
| Once installed, you can configure the default `Preset` parameter used to create the OpenShift Local Cluster in the extension's **Settings** page: | ||
|
|
||
| On **Run Image** form leave default values and press `Start Container` button. | ||
|  | ||
|
|
||
|  | ||
| To create a new OpenShift Local cluster, you have three options: | ||
| 1. Switch to the **Resources** tab on the **Settings** page and press the `Create new ...` button: | ||
|
|
||
| After local container is up and running it can be deployed to OpenShift Local cluster using `Deploy to Kubernetes` command in upper right corner | ||
| of **Container Details** page. | ||
|  | ||
|
|
||
|  | ||
| Then, in the newly opened dialog, configure the cluster to your needs and click on the `Create` button: | ||
|  | ||
|
|
||
| On **Deploy to Kubernetes** form make sure the `Kubernetes Context` field is `crc-admin` and press `Deploy` button. | ||
| 2. From the **Dashboard**, in the `OpenShift Local` section, click on the `Initialize and start` button: | ||
|
|
||
|  | ||
|  | ||
|
|
||
| The bottom part of the page shows the status of deployment. When `Container statuses` contains `Ready (Running)` it means `httpd` server is running in | ||
| OpenShift Local cluster. There is also a link to open OpenShift Developer Console where you manage your local cluster. | ||
| 3. From the **Dashboard**, in the `OpenShift Local` section, click on the dropdown button next to `Initialize and start` and select `Initialize OpenShift Local`: | ||
|
|
||
|  | ||
|  | ||
|
|
||
| Clicking on the link below 'Container statuses` opens `httpd` server index page. | ||
| And then click on the `Initialize` button: | ||
|  | ||
|
|
||
|  | ||
| When a new cluster has been created there should be a new connection visible in the **Resources** page, under the **OpenShift Local** section: | ||
|
|
||
| You have deployed your application to OpenShift! | ||
|  | ||
|
|
||
| ## Requirements | ||
| ## Deployment to OpenShift Local | ||
|
|
||
| You are required to have a working [Podman Desktop][podman-desktop] installation. | ||
| Each preset of OpenShift Local has their own requirements, please check the [documentation][documentation page] for more information. | ||
| To deploy your first application to OpenShift Local, pull the `httpd-24` image from the public Red Hat image registry using the **Pull an Image** page. To do so, open the **Images** page using the activity bar and press `Pull` button in upper right corner: | ||
|
|
||
|  | ||
|
|
||
| ### Preset types | ||
| * Microshift (experimental) | ||
| provides a lightweight and optimized environment with a limited set of services. | ||
| * OpenShift | ||
| provides a single node OpenShift cluster with a fuller set of services, including a web console (requires more resources). | ||
| Paste `registry.access.redhat.com/ubi8/httpd-24` into the `Image to pull` field and press the `Pull Image` button: | ||
|
|
||
|  | ||
|
|
||
| ### Pull-secret | ||
| To pull container images from the registry, a pull secret is necessary. You can get a pull secret by navigating to the dashboard and clicking the "Obtain pull-secret" or opening the [Red Hat OpenShift Local download page][download page] in your browser. | ||
| After the image was sucessfully pulled from the registry press the `Done` button to navigate back to the **Images** page: | ||
|
|
||
|  | ||
|
|
||
| ## Installation | ||
| Request the context menu for the `httpd-24` image you just pulled by clicking on the right most button in the row. Then select the `Push image to OpenShift Local cluster`* menu item: | ||
|
|
||
| #### Prerequisites | ||
|  | ||
|
|
||
| * The extension is not already installed. | ||
| *Note: if the option does not appear on the context menu, try to restart Podman Desktop with `Exit On Close` preference enabled (this is a known issue). | ||
|
|
||
| #### Procedure | ||
| The progress for the `Push` command is available in the Podman Desktop **Tasks** View: | ||
|
|
||
| 1. Open Podman Desktop dashboard. | ||
| 1. Go to the **Extensions** page. | ||
|  | ||
| 1. Swithch to **Catalog** tab and click on `Install` icon in `Red Hat OpenShift Local` extension item. | ||
|  | ||
|  | ||
|
|
||
| ## Features | ||
| When the `Push` command is done, the image is ready to be deployed to the OpenShift Local cluster. First start a local container from the image using the `Run` button: | ||
|
|
||
| * Start/Stop/Delete OpenShift Local presets | ||
| * Change the OpenShift Local preset | ||
| * Change basic configuration | ||
|  | ||
|
|
||
| On the **Run Image** form leave the default values and press `Start Container` button: | ||
|
|
||
| ## Extension Settings | ||
|  | ||
|
|
||
| * Memory, in MiB | ||
| * CPUs, number of cores | ||
| * Preset, Microshift or OpenShift | ||
| * Disksize, in GiB | ||
| * Pull secret file, pull secret for OpenShift | ||
| After the local container is up and running, it can be deployed to OpenShift Local cluster using the `Deploy to Kubernetes` button in the upper right corner | ||
| of **Container Details** page: | ||
|
|
||
|  | ||
|
|
||
| ## Known limitation | ||
| Currently, we do not support the Podman preset of OpenShift Local. Please use preferences to change this: | ||
| On the **Deploy to Kubernetes** form make sure the `Kubernetes Context` field is `crc-admin` and press the `Deploy` button: | ||
|
|
||
|  | ||
|
|
||
| The bottom part of the page shows the status of deployment. When **Container statuses** contains `Ready (Running)` it means the `httpd` server is running in the | ||
| OpenShift Local cluster. There is also a link to open the OpenShift Developer Console where you can manage your local cluster: | ||
|
|
||
|  | ||
|
|
||
| Clicking on the link below **Container statuses** opens the `httpd` server index page: | ||
|
|
||
|  | ||
|
|
||
| You have deployed your application to OpenShift! | ||
|
|
||
| Settings > Preferences > Red Hat OpenShift Local > Preset | ||
|
|
||
|
|
||
| [product page]: https://developers.redhat.com/products/openshift/local | ||
| [product page]: https://developers.redhat.com/products/openshift-local/overview | ||
| [download page]: https://cloud.redhat.com/openshift/create/local | ||
| [documentation page]: https://cloud.redhat.com/openshift/local/documentation | ||
| [podman-desktop]: https://podman-desktop.io/ |