Chapter 3. Using CodeReady Containers
3.1. Setting up CodeReady Containers
The crc setup
command performs operations to set up the environment of your host machine for the CodeReady Containers virtual machine.
This procedure will create the ~/.crc
directory if it does not already exist.
Prerequisites
-
On Linux or macOS, ensure that your user account has permission to use the
sudo
command. On Microsoft Windows, ensure that your user account can elevate to Administrator privileges.
-
Do not run the
crc
executable asroot
(or Administrator). Always run thecrc
executable with your user account. - If you are setting up a new version, capture any changes made to the virtual machine before setting up a new CodeReady Containers release.
Procedure
Set up your host machine for CodeReady Containers:
$ crc setup
Consent for telemetry data collection
The crc setup
command prompts you for optional, anonymous usage data collection to assist with development. No personally identifiable information is collected.
To manually enable telemetry, run the following command:
$ crc config set consent-telemetry yes
To manually disable telemetry, run the following command:
$ crc config set consent-telemetry no
For more information about collected data, see the Red Hat Telemetry data collection notice.
3.2. Starting the virtual machine
The crc start
command starts the CodeReady Containers virtual machine and OpenShift cluster.
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 through the
crc setup
command. For more information, see Setting up CodeReady Containers. - On Microsoft Windows, ensure that your user account can elevate to Administrator privileges.
You have a valid OpenShift user pull secret. Copy or download the pull secret from the Pull Secret section of the Install on Laptop: Red Hat CodeReady Containers page on cloud.redhat.com.
NoteAccessing the user pull secret requires a Red Hat account.
Procedure
Start the CodeReady Containers virtual machine:
$ crc start
- When prompted, supply your user pull secret.
- The cluster takes a minimum of four minutes to start the necessary containers and Operators before serving a request.
-
If you see errors during
crc start
, check the Troubleshooting CodeReady Containers section for potential solutions.
Additional resources
- To change the default resources allocated to the virtual machine, see Configuring the virtual machine.
3.3. Accessing the OpenShift cluster
Access the OpenShift cluster running in the CodeReady Containers virtual machine through the OpenShift web console or client executable (oc
).
3.3.1. Accessing the OpenShift web console
Prerequisites
- A running CodeReady Containers virtual machine. For more information, see Starting the virtual machine.
Procedure
To access the OpenShift web console, follow these steps:
-
Run
crc console
. This will open your web browser and direct it to the web console. Log in as the
developer
user with the password printed in the output of thecrc start
command.Note-
You can also view the password for the
developer
andkubeadmin
users by runningcrc console --credentials
. -
You can initially access the cluster through either the
kubeadmin
ordeveloper
user. Use thedeveloper
user for creating projects or OpenShift applications and for application deployment. Only use thekubeadmin
user for administrative tasks such as creating new users, setting roles, and so on.
-
You can also view the password for the
See Troubleshooting CodeReady Containers if you cannot access the CodeReady Containers OpenShift cluster.
Additional resources
- The OpenShift documentation covers the creation of projects and applications.
3.3.2. Accessing the OpenShift cluster with oc
Prerequisites
- A running CodeReady Containers virtual machine. For more information, see Starting the virtual machine.
Procedure
To access the OpenShift cluster through the oc
command, follow these steps:
Run the
crc oc-env
command to print the command needed to add the cachedoc
executable to yourPATH
:$ crc oc-env
- Run the printed command.
Log in as the
developer
user:$ oc login -u developer https://api.crc.testing:6443
NoteThe
crc start
command prints the password for thedeveloper
user. You can also view it by running thecrc console --credentials
command.You can now use
oc
to interact with your OpenShift cluster. For example, to verify that the OpenShift cluster Operators are available, log in as thekubeadmin
user and run the following command:$ oc config use-context crc-admin $ oc whoami kubeadmin $ oc get co
Note-
CodeReady Containers disables the
monitoring
Operator by default.
-
CodeReady Containers disables the
See Troubleshooting CodeReady Containers if you cannot access the CodeReady Containers OpenShift cluster.
Additional resources
- The OpenShift documentation covers the creation of projects and applications.
3.3.3. Accessing the internal OpenShift registry
The OpenShift cluster running in the CodeReady Containers virtual machine 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 OpenShift registry, follow these steps.
Prerequisites
- A running CodeReady Containers virtual machine. For more information, see Starting the virtual machine.
-
A working
oc
command. For more information, see Accessing the OpenShift cluster withoc
. An installation of
podman
ordocker
.-
For Docker, add
default-route-openshift-image-registry.apps-crc.testing
as an insecure registry. For more information, see the Docker documentation.
-
For Docker, add
Procedure
Check which user is logged in to the cluster:
$ oc whoami
NoteFor demonstration purposes, the current user is assumed to be
kubeadmin
.Log in to the registry as that user with its token:
$ podman login -u kubeadmin -p $(oc whoami -t) default-route-openshift-image-registry.apps-crc.testing --tls-verify=false
Create a new project:
$ oc new-project demo
Pull an example container image:
$ podman pull quay.io/libpod/alpine
Tag the image, including namespace details:
$ podman tag alpine:latest default-route-openshift-image-registry.apps-crc.testing/demo/alpine:latest
Push the container image to the internal registry:
$ podman push default-route-openshift-image-registry.apps-crc.testing/demo/alpine:latest --tls-verify=false
Get imagestreams and verify that the pushed image is listed:
$ oc get is
Enable image lookup in the imagestream:
$ oc set image-lookup alpine
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:
$ oc run demo --image=alpine --command -- sleep 600s
3.4. Deploying a sample application with odo
You can use odo
to create OpenShift projects and applications from the command line. This procedure deploys a sample application to the OpenShift cluster running in the CodeReady Containers virtual machine.
Prerequisites
-
You have installed
odo
. For more information, see Installingodo
in theodo
documentation. - The CodeReady Containers virtual machine is running. For more information, see Starting the virtual machine.
Procedure
To deploy a sample application through odo
, follow these steps:
Log in to the running CodeReady Containers OpenShift cluster as the
developer
user:$ odo login -u developer -p developer
Create a project for your application:
$ odo project create sample-app
Create a directory for your components:
$ mkdir sample-app $ cd sample-app
Create a component from a sample application on GitHub:
$ odo create nodejs --s2i --git https://github.com/openshift/nodejs-ex
NoteCreating a component from a remote Git repository will rebuild the application each time you run the
odo push
command. To create a component from a local Git repository, see Creating a single-component application withodo
in theodo
documentation.Create a URL and add an entry to the local configuration file:
$ odo url create --port 8080
Push the changes:
$ 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:
$ odo url list
- View the deployed application using the generated URL.
Additional resources
-
For more information about using
odo
, see theodo
documentation.
3.5. Stopping the virtual machine
The crc stop
command stops the running CodeReady Containers virtual machine and OpenShift cluster. The stopping process will take a few minutes while the cluster shuts down.
Procedure
Stop the CodeReady Containers virtual machine and OpenShift cluster:
$ crc stop
3.6. Deleting the virtual machine
The crc delete
command deletes an existing CodeReady Containers virtual machine.
Procedure
Delete the CodeReady Containers virtual machine:
$ crc delete
WarningThe
crc delete
command results in the loss of data stored in the CodeReady Containers virtual machine. Save any desired information stored in the virtual machine before running this command.