This is the source repository for OpenShift Origin, based on top of Docker containers and the Kubernetes container cluster manager. Origin is a distribution of Kubernetes optimized for enterprise application development and deployment, used by OpenShift 3 and Atomic Enterprise. OpenShift adds developer and operational centric tools on top of Kubernetes to enable rapid application development, easy deployment and scaling, and long-term lifecycle maintenance for small and large teams and applications.
Features:
- Build web-scale applications with integrated service discovery, DNS, load balancing, failover, health checking, persistent storage, and fast scaling
- Push source code to your Git repository and have image builds and deployments automatically occur
- Easy to use client tools for building web applications from source code
- Templatize the components of your system, reuse them, and iteratively deploy them over time
- Centralized administration and management of application component libraries
- Roll out changes to software stacks to your entire organization in a controlled fashion
- Team and user isolation of containers, builds, and network communication in an easy multi-tenancy system
- Allow developers to run containers securely by preventing root access and isolating containers with SELinux
- Limit, track, and manage the resources teams are using
Learn More:
- Public Documentation
- The Trello Roadmap covers the epics and stories being worked on (click through to individual items)
- Technical Architecture Presentation
- System Architecture design document
For questions or feedback, reach us on IRC on #openshift-dev on Freenode or post to our mailing list.
NOTE: Origin 1.0 has been released releases page. Feedback, suggestions, and testing are all welcome!
Origin runs with the following security policy by default:
- Containers run as a non-root unique user that is separate from other system users
- They cannot access host resources, run privileged, or become root
- They are given CPU and memory limits defined by the system administrator
- Any persistent storage they access will be under a unique SELinux label, which prevents others from seeing their content
- These settings are per project, so containers in different projects cannot see each other by default
- Regular users can run Docker, source, and custom builds
- By default, Docker builds can (and often do) run as root. You can control who can create Docker builds through the
builds/dockerandbuilds/custompolicy resource.
- By default, Docker builds can (and often do) run as root. You can control who can create Docker builds through the
- Regular users and project admins cannot change their security quotas.
See the security documentation for more on managing these restrictions.
The easiest way to run Origin is in a Docker container (Origin requires Docker 1.6.2 or higher). If you'd like to get started with Atomic Enterprise please refer to the quickstart guide.
You'll need to configure the Docker daemon on your host to trust the Docker registry service you'll be starting.
To do this, you need to add "--insecure-registry 172.30.0.0/16" to the Docker daemon invocation, eg:
$ docker -d --insecure-registry 172.30.0.0/16
If you are running Docker as a service via systemd, you can add this argument to the options value in /etc/sysconfig/docker
This will instruct the Docker daemon to trust any Docker registry on the 172.30.0.0/16 subnet, rather than requiring the registry to have a verifiable certificate.
Important!: Docker on non-RedHat distributions (Ubuntu, Debian, boot2docker) has mount propagation PRIVATE, which breaks running Origin inside a container. Please use the Vagrant or binary installation paths on those distributions.
$ sudo docker run -d --name "origin" \
--privileged --net=host \
-v /:/rootfs:ro -v /var/run:/var/run:rw -v /sys:/sys:ro -v /var/lib/docker:/var/lib/docker:rw \
-v /var/lib/openshift/openshift.local.volumes:/var/lib/openshift/openshift.local.volumes \
openshift/origin start
Security! Why do we need to mount your host, run privileged, and get access to your Docker directory? Origin runs as a host agent (like Docker) and starts and stops Docker containers, mounts remote volumes, and monitors the system (/sys) to report performance and health info. You can strip all of these options off and Origin will still start, but you won't be able to run pods (which is kind of the point).
Once the container is started, you can jump into a console inside the container and run the CLI.
$ sudo docker exec -it origin bash
# Start the integrated registry in a container
$ oadm registry --credentials=./openshift.local.config/master/openshift-registry.kubeconfig
# Use the CLI to login, create a project, and then create your app.
$ oc --help
$ oc login
Username: test
Password: test
$ oc new-project test
$ oc new-app -f https://raw.githubusercontent.com/openshift/origin/master/examples/sample-app/application-template-stibuild.json
# See everything you just created!
$ oc status
Any username and password are accepted by default (with no credential system configured). You can view the webconsole at https://localhost:8443/console in your browser - login with the same credentials you used above and you'll see the application you just created.
You can also use the Docker container to run our CLI (sudo docker exec -it origin cli --help) or download the oc command-line client from the releases page for Mac, Windows, or Linux and login from your host with oc login.
You can reset your server by stopping the origin container and then removing it via Docker. The contents of /var/lib/openshift can then be removed. See the public docs for more about running a permanent installation of OpenShift.
We highly recommend trying out the Origin walkthrough, which shows some of the lower level pieces of Origin that will be the foundation for user applications. The walkthrough is accompanied by a blog series on blog.openshift.com that goes into more detail. It's a great place to start, albeit at a lower level than OpenShift 2.
Both Origin and Kubernetes have a strong focus on documentation - see the following for more information about them:
If you run into difficulties running Origin, start by reading through the troubleshooting guide.
The Origin APIs are exposed at https://localhost:8443/oapi/v1/*.
To experiment with the API, you can get a token to act as a user:
$ sudo docker exec -it openshift-origin bash
$ oc login
Username: test
Password: test
$ oc whoami -t
<prints a token>
$ exit
# from your host
$ curl -H "Authorization: bearer <token>" https://localhost:8443/oapi/v1/...
The API documentation can be found here.
-
How does Origin relate to Kubernetes?
Origin is a distribution of Kubernetes optimized for enterprise application development and deployment, used by OpenShift 3 and Atomic Enterprise. Origin embeds Kubernetes and adds additional functionality to offer a simple, powerful, and easy-to-approach developer and operator experience for building applications in containers. Our goal is to do most of that work upstream, with integration and final packaging occurring in Origin.
-
How does Atomic Enterprise relate to Origin and OpenShift?
Two products are built from Origin, Atomic Enterprise and OpenShift. Atomic Enterprise adds operational centric tools to enable easy deployment and scaling and long-term lifecycle maintenance for small and large teams and applications. OpenShift provides a number of developer-focused tools on top of Atomic Enterprise such as image building, management, and enhanced deployment flows.
-
What can I run on Origin?
Origin is designed to run any existing Docker images. In addition you can define builds that will produce new Docker images from a Dockerfile. However the real magic of Origin can be seen when using Source-To-Image builds which allow you to simply supply an application source repository which will be combined with an existing Source-To-Image enabled Docker image to produce a new runnable image that runs your application. We are continuing to grow the ecosystem of Source-To-Image enabled images and documenting them here. Our available images are:
Your application image can be easily extended with a database service with our database images. Our available database images are:
You can develop locally on your host or with a virtual machine, or if you want to just try out Origin download the latest Linux server, or Windows and Mac OS X client pre-built binaries.
First, get up and running with the Contributing Guide.
All contributions are welcome - Origin 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 Origin including how different tests are setup.
If you want to run the test suite, make sure you have your environment set up, and from the origin directory run:
# run the unit tests
$ make check
# 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
# run all of the tests above
$ make test
You'll need etcd installed and on your path for the integration and end-to-end tests to run, and Docker must be installed to run the end-to-end tests. To install etcd you should be able to run:
$ hack/install-etcd.sh
Some of the components of Origin 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
To hack on the web console, check out the assets/README.md file for instructions on testing the console and building your changes.
Origin is licensed under the Apache License, Version 2.0.