Chapter 2. Interacting with OpenShift

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.6.173.0.21 directory, assuming that you use CDK’s default version of OpenShift. 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
Run this command to configure your shell:
eval $(minishift oc-env)

$ minishift oc-env
export PATH="/Users/john/.minishift/cache/oc/v3.6.173.0.21:$PATH"
# Run this command to configure your shell:
# eval $(minishift oc-env)

As a part of the minishift start command, a 'minishift' CLI profile 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

$ oc config use-context minishift

For an introduction to oc usage, see the Get Started with the CLI topic in the OpenShift documentation.

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

$ 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.

To view the available login contexts, run:

oc config view

$ oc config view

To access the OpenShift Web console, you can run this command in a shell after running the minishift command to get the URL of the Web console:

minishift console --url

$ minishift console --url

Alternatively, after starting CDK, you can use the following command to directly open the console in a browser:

minishift console

$ minishift console

To access a service that is exposed with a route, run this command in a shell:

minishift openshift service [-n NAMESPACE] [--url] NAME

$ minishift openshift service [-n NAMESPACE] [--url] NAME

To list all the services in the OpenShift instance, run this command in a shell:

minishift openshift service list

$ minishift openshift service list

For more information on exposing services refer also to Exposing Services.

To access OpenShift logs, run the logs command after starting CDK:

minishift logs

$ minishift logs

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

$ minishift openshift config view

To show the node configuration instead of the master configuration, specify the target flag.

 minishift openshift config set --patch '{"corsAllowedOrigins": [".*"]}'

$  minishift openshift config set --patch '{"corsAllowedOrigins": [".*"]}'

minishift openshift config set --patch '{\"corsAllowedOrigins\": [\".*\"]}'

$ minishift openshift config set --patch '{\"corsAllowedOrigins\": [\".*\"]}'

minishift openshift config set --patch "{\"corsAllowedOrigins\": [\".*\"]}"

$ minishift openshift config set --patch "{\"corsAllowedOrigins\": [\".*\"]}"

minishift openshift config set --patch '{"routingConfig": {"subdomain": "<IP-ADDRESS>.xip.io"}}'

$ minishift openshift config set --patch '{"routingConfig": {"subdomain": "<IP-ADDRESS>.xip.io"}}'

There are several ways you can expose your service after you deploy it on OpenShift. The following sections describes the various methods and when to use them.

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

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.

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 the minishift and oc commands:

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

$ 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 CDK VM IP and the exposed NodePort service.

mysql --user=root --password=foo --host=$(minishift ip) --port=30907

$ mysql --user=root --password=foo --host=$(minishift ip) --port=30907

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

$ oc port-forward POD [LOCAL_PORT:]REMOTE_PORT

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.

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.