# vagrant-openshift

**Repository Path**: mirrors_openshift/vagrant-openshift

## Basic Information

- **Project Name**: vagrant-openshift
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-08-22
- **Last Updated**: 2026-02-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

== OpenShift Origin Build Tools

image:https://travis-ci.org/openshift/vagrant-openshift.svg?branch=master[link=https://travis-ci.org/openshift/vagrant-openshift]

This is a link:http://www.vagrantup.com[Vagrant] 1.7.2+ plugin that adds vagrant commands and provisioners to
build and test link:http://openshift.github.io[OpenShift Origin].

NOTE: This plugin requires link:https://www.vagrantup.com/downloads.html[Vagrant 1.7.2+]

NOTE: Instructions below generally assume a Linux-like command line and may require modifications for other environments.

=== Features

* Compatible with VMs run via link:https://www.virtualbox.org[VirtualBox], link:https://github.com/mitchellh/vagrant-aws[AWS],
  link:https://github.com/pradels/vagrant-libvirt[libvirt], link:https://github.com/cloudbau/vagrant-openstack-plugin[OpenStack],
  or link:https://github.com/tknerr/vagrant-managed-servers[managed] providers.
* Provides commands to install build dependencies, sync repositories, and run tests

===== Using with OpenShift v2

v2 (aka M4) is no longer supported on the master branch or in the
published rubygems.org version of this plugin.  You must checkout the
link:https://github.com/openshift/vagrant-openshift/tree/v2[v2 branch of this repository]
in order to use the plugin with v2 and follow the documentation there.

=== Installing

Like other plugins, this gem will be installed in your `~/.vagrant.d/gems/` directory.

===== From source

To work on the *vagrant-openshift* plugin, clone this repository and use
link:http://gembundler.com[Bundler] to get the dependencies:

You *MUST* use bundler < = 1.10.5 or bundler = 1.12.5 when building this gem, as it is required by the vagrant gem.

[source, sh]
----
$ gem install bundler -v '1.12.5'
$ bundle _1.12.5_
----

Compile using Rake:

[source, sh]
----
$ bundle _1.12.5_ exec rake
----

===== From rubygems.org

Install the published version of this plugin:

[source, sh]
----
$ vagrant plugin install vagrant-openshift
----

=== Getting started with OpenShift v3

This plugin works in concert with the
link:https://github.com/openshift/origin/blob/master/Vagrantfile[OpenShift Origin Vagrantfile]
to build and update OpenShift development environments.

==== Clone the OpenShift Origin repositories

The upstream OpenShift Origin projects will be git-cloned locally
under your GOPATH (you don't need to have golang or other build
requirements installed locally).  These will be set as the git "upstream"
remote. Projects you have forked into your github account will also have
that account as the git "origin" remote.

Add your GOPATH if you don't already have one for golang:
[source, sh]
----
$ echo "export GOPATH=~/code" >> ~/.bash_profile   # ~/code can be any dir
$ source ~/.bash_profile
$ mkdir -p $GOPATH
----

Then clone the repositories into your GOPATH.
[source, sh]
----
$ cd $GOPATH
$ vagrant origin-local-checkout -u <github username>
$ cd src/github.com/openshift/origin
----

==== Initialize local vagrant conf

Generate a `.vagrant-openshift.json` in your OpenShift Origin repo that
you may modify later to match your vagrant requirements:

[source, sh]
----
$ vagrant origin-init --stage inst --os (fedora|centos7|rhel7|rhelatomic7) <instance name>
----

==== Start the machine

===== VirtualBox

Running with the default VirtualBox provider:

NOTE: If you are trying to refresh an existing image, you'll want to remove the current image with `vagrant box list` and `vagrant box remove <box_name>`

[source, sh]
----
$ vagrant up --provider=virtualbox
----

NOTE: See link:#other-providers[Other Providers] below for launching VMs from other providers.


==== Making Subsequent Changes

* Building updated code from edits in your local repository clones:

[source, sh]
----
$ vagrant sync-origin
----

For some providers, your local repositories are automatically synchronized
to the remote VM. If not, the `--source` option can be used to do so
before building.

In addition to the OpenShift binary itself, by default a number of
component Docker images are built as well, which can take a long time. To
rebuild only the OpenShift binary, use the `--no-images` option.

==== Running Tests

[source, sh]
----
$ vagrant test-origin --all
----


=== Developer environment

To enable easy customization of the build environment, any files placed under `\~/.openshiftdev/home.d` will be copied to
the vagrant user home directory. For example: `~/.openshiftdev/home.d/.bash_profile` will be copied to `.bash_profile`
on the vagrant VM.

==== Configuring Docker and Golang versions for tests

If the version of OpenShift that is being tested requires a version
of Golang or Docker that is not default in the RPM streams for the
operating system used for the image, `vagrant-openshift` allows for
customization of the image.

To build a new image with the versions of Golang and Docker necessary,
begin with an 'os' stage:
[source, sh]
----
$ vagrant origin-init --stage os --os rhel7 --instance-type c4.xlarge "${instance_name}"
----

Then, you may provide the following information to customize your image:

* URLs to repositories containing the desired Docker and/or Golang RPMs to use during the install
* names of repositores already installed on the OS that you want to use during the install
* versions of Golang and/or Docker to install

Any RPM repositories you add by providing URLs will only be enabled for
the duration of the installation. Only the repositories you provide using
URLs or those that you name explcitly will be enabled during the install.

For instance, some installation of  OpenShift Origin could want custom
Go and Docker versions, both of which must be installed from custom URLs.
Furthermore, some of the Docker dependencies may have up-to-date versions
in the RHEL streams, so the following commands would be used to configure
the image base:
[source, sh]
----
$ vagrant install-golang --golang.repourl=http://some.golang.rpm.repository.com/ \
                         --golang.version=1.6.2

$ vagrant install-docker --docker.repourl=http://some.docker.rpm.repository.com/ \
                         --docker.repo=oso-rhui-rhel-server-releases \
                         --docker.version=1.10.3
----

=== Other Providers

Your origin repo Vagrantfile can use other providers than the default
VirtualBox provider for creating VMs. Provider configuration consults
outside configuration files so that the repository Vagrantfile does not
have to be modified in most cases. See the relevant provider section in
the Vagrantfile to learn what parameters are available.

If you are starting with a plain operating system host image (which is
likely to be the case) then you have a bit of setup to do to prepare
your host for building and running after creation. Consult the
link:#initial-setup[Initial Setup] section for details.

==== AWS/EC2

* Install the latest vagrant-aws plugin.

Install plugin from rubygems:
----
$ vagrant plugin install vagrant-aws
----

Or follow the link:https://github.com/mitchellh/vagrant-aws/blob/master/README.md#development[build steps] to build from source.

You now need some AWS-specific configuration to specify which AMI to use.

* Ensure your AWS credentials file is present at `~/.awscred`; it should have the following entries filled in:

----
AWSAccessKeyId=<AWS API Key>
AWSSecretKey=<AWS API Secret>
AWSKeyPairName=<Keypair name>
AWSPrivateKeyPath=<SSH Private key>
----

* Re-create your `.vagrant-openshift.json` file with updated AWS settings:

[source, sh]
----
$ vagrant origin-init --stage inst --os (fedora|centos7|rhel7|rhelatomic7) <instance name>
----

The instance name will be applied as a tag and should generally be
specific to you and OpenShift so that you can identify the VM among any
others in your account. It will be stored in the config file.

The Red Hat OpenShift team shares an account that provides pre-built
AMIs for the quickest startup possible, so this command will search for
the latest version of that AMI. If your account doesn't have this AMI, you'll need to supply
a base AMI in your repository's `.vagrant-openshift.json` file under the
`aws.ami` key.

* Start the AWS machine

[source, sh]
----
vagrant up --provider=aws
----

TIP: Be sure to rerun origin-init for each subsequent run of `vagrant up --provider=aws` to pick up the last built ami.

NOTE: Requires latest link:https://github.com/mitchellh/vagrant-aws[AWS] provider.

NOTE: You can use the link:https://github.com/mikery/vagrant-ami[Vagrant-AMI] plugin to create an AMI from a running AWS machine.


==== OpenStack

* Install the latest vagrant-openstack-plugin. See: https://github.com/cloudbau/vagrant-openstack-plugin.

Install plugin from rubygems:
----
$ vagrant plugin install vagrant-openstack-plugin
----

NOTE: On some systems (e.g. mac) doing `export NOKOGIRI_USE_SYSTEM_LIBRARIES=1` can help make the above command work.

* Edit `~/.openstackcred` and update your OpenStack credentials, endpoint and tenant name.

----
OSEndpoint=<OpenStack Endpoint URL, e.g. http://openshift.example.com:5000/v2.0/tokens>
OSUsername=<OpenStack Username>
OSAPIKey=<OpenStack Password>
OSKeyPairName=<Keypair name as registered in OpenStack>
OSPrivateKeyPath=<path to that SSH Private key>
OSTenant=<OpenStack Tenant/Project Name, see it at the top in OpenStack web UI>
OSFloatingIP=<specific floating ip or ':auto' if floating ip is desired>
OSFloatingIPPool=<specific pool or 'false' (to use first found) if floating ip is desired>
----

* Edit `.vagrant-openshift.json` and update the openstack provider
  section. You'll need to indicate at least the base image
  you'd like to start, as well as the user to access with.

----
  "openstack": {
    "image": "Fedora-Cloud-Base-20141203-21.x86_64",
    "ssh_user": "fedora"
  }
----

* Start the OpenStack machine

[source, sh]
----
vagrant up --provider=openstack
----

NOTE: Requires latest link:https://github.com/cloudbau/vagrant-openstack-plugin[OpenStack] provider.


==== Libvirt

* If using a recent version of Fedora, you can install vagrant-libvirt directly using yum/dnf.  Otherwise you will need to follow the `vagrant plugin install` instructions below.

[source, sh]
----
sudo yum install vagrant-libvirt
----

* Install the vagrant-libvirt plugin dependencies (only if `sudo yum install vagrant-libvirt` didn't work)

[source, sh]
----
sudo yum install libxslt-devel libxml2-devel libvirt-devel ruby-devel rubygems
----

* Install the vagrant-libvirt plugin *(only if `sudo yum install vagrant-libvirt` didn't work)*

[source, sh]
----
vagrant plugin install vagrant-libvirt
----

NOTE: This may require modifying the system linker as described in
      link:https://github.com/mitchellh/vagrant/issues/5118[this issue]:

----
sudo alternatives --set ld /usr/bin/ld.gold
----

* Add your user to the libvirt group - this gives authorization to connect to libvirtd

[source, sh]
----
sudo usermod -a -G libvirt $USER
----

* Log out and log in for the group change to take effect

* Start the libvirt machine

[source, sh]
----
vagrant up --provider=libvirt
----

NOTE: Requires latest link:https://github.com/pradels/vagrant-libvirt[libvirt] provider

===== Managed

Running on other environments which are not managed by Vagrant directly.

* Install the vagrant-managed-servers plugin

[source, sh]
----
vagrant plugin install vagrant-managed-servers
----

* Edit the Vagrantfile and update the managed section to update the IP address, User name and SSH key.

----
managed.server = "HOST or IP of machine"
override.ssh.username = "root"
override.ssh.private_key_path = "~/.ssh/id_rsa"
----

* Connect to the manually managed machine

[source, sh]
----
vagrant up --provider=managed
----

NOTE: Requires latest link:https://github.com/tknerr/vagrant-managed-servers[Managed] provider

=== Initial Setup

Ideally you would be able to use an image with the operating system,
dependencies, and OpenShift already installed so you can just start
hacking. But at this time that is not available for all providers.

Images may be thought of as being at one of four stages:

1. "os" - The base OS image (use a "minimal" one).
2. "deps" - OpenShift runtime dependencies and build requirements are installed.
3. "inst" - OpenShift code, images, and binaries are built and installed

You may want to create images that snapshot the output at each of
these stages, as the rate of change and amount of time to create each
is different.

After using `vagrant up --provider=<provider>` to start a host with only
a basic operating system on it (Fedora 21+ or CentOS 7 should suffice),
you will need to install the build tools and other dependencies for
building and running OpenShift. The following vagrant commands should
help with this:

[source, sh]
----
$ vagrant build-origin-base
$ vagrant build-origin-base-images
$ vagrant install-origin-assets-base
----

Given this base foundation, you may want to `vagrant package` the result before proceeding to install OpenShift code.

[source, sh]
----
$ vagrant install-origin
$ vagrant build-origin-base-images  # pick up updates if older "deps" base reused
$ vagrant build-origin --images
$ vagrant build-sti --binary-only
----

=== Testing openshift/origin-aggregated-logging or openshift/origin-metrics

NOTE: You will still need to clone the OpenShift Origin repo as above, in order
to use the Vagrantfile and the contrib/vagrant directory.
origin-aggregated-logging and origin-metrics currently have no vagrant support.

==== Clone the OpenShift Origin aggregated logging or metrics repositories

Use `vagrant origin-local-checkout` as above link:#clone-the-openshift-origin-repositories[Clone the OpenShift Origin repositories], except use `--repo origin-aggregated-logging`:
[source, sh]
----
$ cd $GOPATH
$ vagrant origin-local-checkout --repo origin-aggregated-logging -u <github username>
# run the remaining vagrant commands from $GOPATH/src/github.com/openshift/origin
$ pushd $GOPATH/src/github.com/openshift/origin
----

==== Initialize local vagrant conf

Same as above for origin - see link:#initialize-local-vagrant-conf[Initialize local vagrant conf]
You must be in `$GOPATH/src/github.com/openshift/origin` to run this.

==== Start the machine

Same as above for origin - see link:#start-the-machine[Start the machine]
You must be in `$GOPATH/src/github.com/openshift/origin` to run this.

==== Making Subsequent Changes

* Building updated code from edits in your local repository clones:

[source, sh]
----
$ vagrant sync-origin-aggregated-logging
----

For some providers, your local repositories are automatically synchronized
to the remote VM. If not, the `--source` option can be used to do so
before building.
You must be in `$GOPATH/src/github.com/openshift/origin` to run this.

==== Running Tests

[source, sh]
----
$ vagrant test-origin-aggregated-logging [--env NAME=VAR] ...
----
You must be in `$GOPATH/src/github.com/openshift/origin` to run this.

== Notice of Export Control Law

This software distribution includes cryptographic software that is subject to the U.S. Export Administration Regulations (the "*EAR*") and other U.S. and foreign laws and may not be exported, re-exported or transferred (a) to any country listed in Country Group E:1 in Supplement No. 1 to part 740 of the EAR (currently, Cuba, Iran, North Korea, Sudan & Syria); (b) to any prohibited destination or to any end user who has been prohibited from participating in U.S. export transactions by any federal agency of the U.S. government; or (c) for use in connection with the design, development or production of nuclear, chemical or biological weapons, or rocket systems, space launch vehicles, or sounding rockets, or unmanned air vehicle systems.You may not download this software or technical information if you are located in one of these countries or otherwise subject to these restrictions. You may not provide this software or technical information to individuals or entities located in one of these countries or otherwise subject to these restrictions. You are also responsible for compliance with foreign law requirements applicable to the import, export and use of this software and technical information.