OpenShift 3 Alpha

This is the source repository for the next version of OpenShift - the third architectural revision. It is based around Docker containers and images and the Kubernetes container management solution. OpenShift adds developer centric and organization centric workflows on top of Kubernetes, and much of the core functionality of OpenShift is designed as plugins to the core Kubernetes concepts.

Please see the OpenShift 3 Project Enhancement Proposal (PEP) for a deeper discussion of the features you see here.

NOTE: OpenShift is in alpha and is not intended for production use yet. However we welcome feedback and testing as we approach our first beta. The mailing list is a great way to tune in.

Getting Started

The simplest way to start is to run OpenShift Origin in a Docker container:

$ docker run -d --name "openshift-origin" --net=host --privileged \
-v /var/run/docker.sock:/var/run/docker.sock \
openshift/origin start

Note that this won't hold any data after a restart, so you'll need to use a data container or mount a volume at /var/lib/openshift to preserve that data. For example, create a /var/lib/openshift folder on your Docker host, and then start origin with the following:

$ docker run -d --name "openshift-origin" --net=host --privileged \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /var/lib/openshift:/var/lib/openshift \
openshift/origin start

Once the container is started, you will likely want to attach to it in order to execute commands:

$ docker exec -it openshift-origin bash
$ openshift cli --help

Start Developing

You can develop locally on your host or with a virtual machine, or if you want to just try out OpenShift download the latest Linux server, or Windows and Mac OS X client pre-built binary.

First, get up and running with the Contributing Guide.

Once setup, you can:

1. Run a build

   $ hack/build-go.sh
   

2. Start an OpenShift all-in-one server (includes everything you need to try OpenShift)

   $ _output/local/go/bin/openshift start
   

3. In another terminal window, switch to the directory and start an app:

   $ cd $GOPATH/src/github.com/openshift/origin
   $ _output/local/go/bin/openshift kubectl create -f examples/hello-openshift/hello-pod.json
   

Once that's done, open a browser on your machine and open http://localhost:6061; you should see a 'Welcome to OpenShift' message.

How Does This Work?

This example runs the 'openshift/hello-openshift' Docker image inside a Docker container, but managed by OpenShift and Kubernetes.

• At the Docker level, that image binds to port 8080 within a container and prints out a simple 'Hello OpenShift' message on access.
• At the Kubernetes level, we map that bound port in the container to port 6061 on the host so that we can access it via the host browser.
• When you created the container, Kubernetes decided which host to place the container on by looking at the available hosts and selecting one with available space. The agent that runs on each node (part of the OpenShift all-in-one binary, called the Kubelet) saw that it was now supposed to run the container and instructed Docker to start the container.

OpenShift brings all of these pieces (and a client) together in a single, easy to use binary. The following examples show the other OpenShift specific features that live above the Kubernetes runtime like image building and deployment flows.

Other Examples

• OpenShift full walkthrough
• Kubernetes walkthrough
• Kubernetes guestbook
• OpenShift guestbook template takes the previous example and templatizes it

Remember, you can pass a URL to -f when using the kubectl command, so you can download the latest release and pass a URL to the content on GitHub so you don't even need clone the source.

Troubleshooting

If you run into difficulties running OpenShift, start by reading through the troubleshooting guide.

Docker registry

In order to use an image built from an OpenShift build, you'll need to push that image into a Docker registry. You can use a private Docker registry or the DockerHub.

Private docker registry

To setup private docker registry you can either follow the registry quick-start or use sample-app example to host a registry on OpenShift. In your buildConfig you should pass the fully qualified registry name of the image you want to push myregistry.com:8080/username/imagename.

DockerHub

To push images to the DockerHub you need to login using docker login command. This command will create a file named .dockercfg in your home directory containing your Hub credentials. If you're running the OpenShift all-in-one as a different user, you'll need to copy this file into that other user's home directory. When the build completes this file will be read by Docker, and the credentials inside of it will be used to push your image.

NOTE: You must tag your built image as <username-for-credentials>/<imagename> when using the DockerHub.

Design Documents

OpenShift designs:

• OpenShift 3 PEP
• Orchestration Overview

Kubernetes designs are in the Kubernetes docs dir

API

The OpenShift APIs are exposed at http://localhost:8080/osapi/v1beta1/*.

• Builds
• http://localhost:8080/osapi/v1beta1/builds
• http://localhost:8080/osapi/v1beta1/buildConfigs
• http://localhost:8080/osapi/v1beta1/buildLogs
• http://localhost:8080/osapi/v1beta1/buildConfigHooks
• Deployments
• http://localhost:8080/osapi/v1beta1/deployments
• http://localhost:8080/osapi/v1beta1/deploymentConfigs
• Images
• http://localhost:8080/osapi/v1beta1/images
• http://localhost:8080/osapi/v1beta1/imageRepositories
• http://localhost:8080/osapi/v1beta1/imageRepositoryMappings
• Templates
• http://localhost:8080/osapi/v1beta1/templateConfigs
• Routes
• http://localhost:8080/osapi/v1beta1/routes
• Projects
• http://localhost:8080/osapi/v1beta1/projects
• Users
• http://localhost:8080/osapi/v1beta1/users
• http://localhost:8080/osapi/v1beta1/userIdentityMappings
• OAuth
• http://localhost:8080/osapi/v1beta1/accessTokens
• http://localhost:8080/osapi/v1beta1/authorizeTokens
• http://localhost:8080/osapi/v1beta1/clients
• http://localhost:8080/osapi/v1beta1/clientAuthorizations

The Kubernetes APIs are exposed at http://localhost:8080/api/v1beta2/*:

• http://localhost:8080/api/v1beta2/pods
• http://localhost:8080/api/v1beta2/services
• http://localhost:8080/api/v1beta2/replicationControllers
• http://localhost:8080/api/v1beta2/operations

OpenShift and Kubernetes integrate with the Swagger 2.0 API framework which aims to make it easier to document and write clients for RESTful APIs. When you start OpenShift, the Swagger API endpoint is exposed at http://localhost:8080/swaggerapi. The Swagger UI makes it easy to view your documentation - to view the docs for your local version of OpenShift start the server with CORS enabled:

$ openshift start --cors-allowed-origins=.*

and then browse to http://openshift3swagger-claytondev.rhcloud.com (which runs a copy of the Swagger UI that points to localhost:8080 by default). Expand the operations available on v1beta1 to see the schemas (and to try the API directly).

FAQ

1. How does OpenShift relate to Kubernetes?

   OpenShift embeds Kubernetes and adds additional functionality to offer a simple, powerful, and easy-to-approach developer and operator experience for building applications in containers. Kubernetes today is focused around composing containerized applications - OpenShift adds building images, managing them, and integrating them into deployment flows. Our goal is to do most of that work upstream, with integration and final packaging occurring in OpenShift. As we iterate through the next few months, you'll see this repository focus more on integration and plugins, with more and more features becoming part of Kubernetes.

   OpenShift tracks the Kubernetes upstream at github.com/openshift/kubernetes. See the wiki in that project for more on how we manage the process of integrating prototyped features.

2. What about geard?

   Geard started as a prototype vehicle for the next generation of the OpenShift node - as an orchestration endpoint, to offer integration with systemd, and to prototype network abstraction, routing, SSH access to containers, and Git hosting. Its intended goal is to provide a simple way of reliably managing containers at scale, and to offer administrators tools for easily composing those applications (gear deploy).

   With the introduction of Kubernetes, the Kubelet, and the pull model it leverages from etcd, we believe we can implement the pull-orchestration model described in orchestrating geard, especially now that we have a path to properly limit host compromises from affecting the cluster.
   The pull-model has many advantages for end clients, not least of which that they are guaranteed to eventually converge to the correct state of the server. We expect that the use cases the geard endpoint offered will be merged into the Kubelet for consumption by admins.

   systemd and Docker integration offers efficient and clean process management and secure logging aggregation with the system. We plan on introducing those capabilities into Kubernetes over time, especially as we work with the Docker upstream to limit the impact of the Docker daemon's parent child process relationship with containers, where death of the Docker daemon terminates the containers under it

   Network links and their ability to simplify how software connects to other containers is planned for Docker links v2 and is a capability we believe will be important in Kubernetes as well (see issue 494 for more details).

   The geard deployment descriptor describes containers and their relationships and will be mapped to deployment on top of Kubernetes. The geard commandline itself will likely be merged directly into the openshift command for all-in-one management of a cluster.

Contributing

All contributions are welcome - OpenShift uses the Apache 2 license and does not require any contributor agreement to submit patches. Please open issues for any bugs or problems you encounter, ask questions on the OpenShift IRC channel (#openshift-dev on freenode), or get involved in the Kubernetes project at the container runtime layer.

See HACKING.md for more details on developing on OpenShift including how different tests are setup.

If you want to run the test suite, make sure you have your environment from above set up, and from the origin directory run:

# run the unit tests
$ hack/test-go.sh

# run a simple server integration test
$ hack/test-cmd.sh

# run the integration server test suite
$ hack/test-integration.sh

# run the end-to-end test suite
$ hack/test-end-to-end.sh

You'll need etcd installed and on your path for the integration tests to run. To install etcd you should be able to run:

$ hack/install-etcd.sh

Some of the components of OpenShift run as Docker images, including the builders and deployment tools in images/builder/docker/* and 'images/deploy/*`. To build them locally run

$ hack/build-images.sh

License

OpenShift is licensed under the Apache License, Version 2.0.