Chapter 3. Interacting with OpenShift using Container Development Kit
CDK creates a virtual machine and provisions a local, single-node OpenShift cluster in this VM. The following sections describe how CDK can assist you in interacting and configuring your local OpenShift cluster.
For details about managing the CDK VM, see the Basic Usage section.
3.1. Using the OpenShift Client Binary (oc)
3.1.1. Overview
The minishift start command creates an OpenShift cluster using the cluster up approach. For this purpose it copies the oc binary onto your host.
The oc binary is located in the $MINISHIFT_HOME/cache/oc/v3.11.374 directory, assuming that you use the default OpenShift version for CDK. You can add this binary to your PATH using minishift oc-env, which displays the command you need to type into your shell.
The output of minishift oc-env differs depending on the operating system and the shell type.
$ minishift oc-env export PATH="/home/user/.minishift/cache/oc/v3.11.374:$PATH" # Run this command to configure your shell: # eval $(minishift oc-env)
3.1.2. CDK CLI Profile
As part of the minishift start command, a CLI profile named minishift is also created. This profile, also known as a context, contains the configuration to communicate with your OpenShift cluster.
CDK activates this context automatically, but if you need to switch back to it after, for example, logging into another OpenShift instance, you can run:
$ oc config use-context minishift
For an introduction to oc usage, see the Get Started with the CLI topic in the OpenShift documentation.
3.1.3. Logging Into the Cluster
By default, cluster up uses AllowAllPasswordIdentityProvider to authenticate against the local cluster. This means any non-empty user name and password can be used to login to the local cluster.
The recommended user name and password is developer and developer, respectively. This is because they are already assigned to the default project myproject and also can impersonate the administrator. This allows you to run administrator commands using the --as system:admin parameter.
To login as administrator, use the system account:
$ oc login -u system:admin
In this case, client certificates are used. The certificates are stored in ~/.kube/config. The cluster up command installs the appropriate certificates as a part of the bootstrap.
If you run the command oc login -u system -p admin, you will log in but not as an administrator. Instead, you will be logged in as an unprivileged user with no particular rights.
To view the available login contexts, run:
$ oc config view
3.1.4. Accessing the Web Console
To access the OpenShift Web console, you can run this command in a shell after starting CDK to get the URL of the Web console:
$ minishift console --url
Alternatively, after starting CDK, you can use the following command to directly open the console in a browser:
$ minishift console
3.1.5. Accessing OpenShift Services
To access a service that is exposed with a route, run this command in a shell:
$ minishift openshift service [-n NAMESPACE] [--url] NAME
For more information refer also to Exposing Services.
3.1.6. Viewing OpenShift Logs
To access OpenShift logs, run the following command after starting CDK:
$ minishift logs
3.1.7. Updating OpenShift Configuration
While OpenShift is running, you can view and change the master or the node configuration of your cluster.
To view the OpenShift master configuration file master-config.yaml, run the following command:
$ minishift openshift config view
To show the node or kubeapi-server configuration instead of the master configuration, specify the target flag.
For details about the view sub-command, see the minishift openshift config view synopsis.
After you update the OpenShift configuration, OpenShift will transparently restart.
3.1.7.1. Example: Configuring cross-origin resource sharing
In this example, you configure cross-origin resource sharing (CORS) by updating the OpenShift master configuration to allow additional IP addresses to request resources.
By default, OpenShift only allows cross-origin resource requests from the IP address of the cluster or from localhost. This setting is stored in the corsAllowedOrigins property of the master configuration file master-config.yaml.
To change the property value and allow cross-origin requests from all domains, run the following command:
$ minishift openshift config set --patch '{"corsAllowedOrigins": [".*"]}'If you get the error The specified patch need to be a valid JSON. when you run the above command, you need to modify the above command depending on your operating system, your shell environment and its interpolation behavior.
For example, if you use PowerShell on Windows 7 or 10, modify the above command to:
PS> minishift.exe openshift config set --patch '{\"corsAllowedOrigins\": [\".*\"]}'If you use Command Prompt, use the following:
C:\> minishift.exe openshift config set --patch "{\"corsAllowedOrigins\": [\".*\"]}"3.1.7.2. Example: Changing the OpenShift Routing Suffix
In this example, you change the OpenShift routing suffix in the master configuration.
If you use a static routing suffix, you can set the routing-suffix flag as part of the minishift start command. By default, CDK uses a dynamic routing prefix based on nip.io, in which the IP address of the VM is a part of the routing suffix, for example 192.168.99.103.nip.io.
If you experience issues with nip.io, you can use xip.io, which is based on the same principles.
To set the routing suffix to xip.io, run the following command:
$ minishift openshift config set --patch '{"routingConfig": {"subdomain": "<IP-ADDRESS>.xip.io"}}'
Make sure to replace IP-ADDRESS in the above example with the IP address of your CDK VM. You can retrieve the IP address by running the minishift ip command.
3.1.8. Add Component to OpenShift Cluster
To add a component to a running OpenShift cluster, use the following:
$ minishift openshift component add <component-name>
3.1.8.1. Example: Add service-catalog component
In this example, the service-catalog component can be added as follows:
$ minishift openshift component add service-catalog
3.1.9. List Valid Components to Add to OpenShift Cluster
To list valid components which can be added to the running OpenShift cluster, use the following:
$ minishift openshift component list
3.2. Exposing Services
3.2.1. Overview
There are several ways you can expose your service after you deploy it on OpenShift. The following sections describe the various methods and when to use them.
3.2.2. Routes
If you are deploying a Web application, the most common way to expose it is by a route. A route exposes the service as a host name. You can create a route using the Web console or the CLI:
$ oc expose svc/frontend --hostname=www.example.com
To see a full example of creating an application and exposing it with a route, see the Deploying a Sample Application section.
3.2.3. NodePort Services
In case the service you want to expose is not HTTP based, you can create a NodePort service. In this case, each OpenShift node will proxy that port into your service. To access this port on your CDK VM, you need to configure an Ingress IP using oc expose with the parameter type=LoadBalancer.
A common use-case for Ingress IP Self-Service is the ability to expose a database service. The following example shows the complete workflow to create and expose a MariaDB instance using CDK:
$ minishift start
$ eval $(minishift oc-env)
$ oc new-app -e MYSQL_ROOT_PASSWORD=admin https://raw.githubusercontent.com/openshift/origin/master/examples/db-templates/mariadb-persistent-template.json
$ oc rollout status -w dc/mariadb
$ oc expose dc mariadb --type=LoadBalancer --name=mariadb-ingress
$ oc export svc mariadb-ingress
....
ports:
- nodePort: 30907
....
After the service is exposed, you can access MariaDB with the mysql CLI using the CDK VM IP and the exposed NodePort service.
$ mysql --user=root --password=admin --host=$(minishift ip) --port=30907
3.2.4. Port Forwarding
3.2.4.1. Using oc port-forward
If you want to quickly access a port of a specific pod of your cluster, you can also use the oc port-forward command of the OpenShift CLI.
$ oc port-forward POD [LOCAL_PORT:]REMOTE_PORT
3.2.4.2. Using VirtualBox tools
In case you’re using the VirtualBox driver plug-in there is another method you can use for port forwarding. This method will allow for permanent port forwarding as well as for forwarding multiple ports at the same time. This method requires you to set up a nodePort as outlined above.
If we go by the example above, we can do the following:
$ VBoxManage controlvm minishift natpf1 "mariadb,tcp,,3306,,30907"
This will allow us to communicate with the mariadb service on localhost:3306 which might be convenient if you don’t want to change default ports. Additionally, an important advantage of this way of forwarding ports is that we can talk to a service as opposed to just a single pod.
3.3. Accessing the OpenShift Docker Registry
3.3.1. Overview
OpenShift provides an integrated Docker registry which can be used for development as well. Images present in the registry can directly be used for applications, speeding up the local development workflow.
3.3.2. Logging Into the Registry
-
Start CDK and add the
ocbinary to thePATH. For a detailed example, see the CDK Quickstart section. - Make sure your shell is configured to reuse the CDK Docker daemon.
Log into the OpenShift Docker registry.
$ docker login -u developer -p $(oc whoami -t) $(minishift openshift registry)
3.3.3. Deploying Applications
The following example shows how to deploy an OpenShift application directly from a locally-built Docker image. This example uses the OpenShift project myproject. This project is automatically created by minishift start.
- Make sure your shell is configured to reuse the CDK Docker daemon.
- Build the Docker image as usual.
Tag the image against the OpenShift registry:
$ docker tag my-app $(minishift openshift registry)/myproject/my-app
Push the image to the registry to create an image stream with the same name as the application:
$ docker push $(minishift openshift registry)/myproject/my-app
Create an application from the image stream and expose the service:
$ oc new-app --image-stream=my-app --name=my-app $ oc expose service my-app
If you want to deploy an application using oc run --image […] then exposed internal registry route doesn’t work. You should use internal registry IP along with your project and app to deploy, as following:
$ oc run myapp --image 172.30.1.1:5000/myproject/myapp
