Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# Contributing to Microshift
# Contributing to MicroShift

If you would like to develop Microshift locally, you can follow this guide on getting
If you would like to develop MicroShift locally, you can follow this guide on getting
it installed and running through the provided Makefile.

This guide will primarily focus on running Microshift within a VM using Vagrant.
This guide will primarily focus on running MicroShift within a VM using Vagrant.


## (optional) Developing with Vagrant
Expand All @@ -18,7 +18,7 @@ system of your choice. For this example we will be looking at a [fedora 34 cloud
image](https://app.vagrantup.com/fedora/boxes/34-cloud-base), however you can substitute any vagrant image of your choice.


First, navigate to the Microshift directory on your host system, or another designated
First, navigate to the MicroShift directory on your host system, or another designated
directory where we will be storing the Vagrantfile.


Expand Down Expand Up @@ -138,7 +138,7 @@ and click on the button to connect to it in a remote window.
](https://medium.com/@lopezgand/connect-visual-studio-code-with-vagrant-in-your-local-machine-24903fb4a9de))*


## Running Microshift Locally
## Running MicroShift Locally

### Pre-Installation

Expand Down Expand Up @@ -175,9 +175,9 @@ git clone https://github.com/redhat-et/microshift.git
cd microshift
```

### Building Microshift
### Building MicroShift

Now we can build Microshift:
Now we can build MicroShift:

```sh
make build
Expand Down
40 changes: 20 additions & 20 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,58 +1,58 @@
# Microshift
# MicroShift

Microshift is a research project that is exploring how OpenShift<sup>1</sup> Kubernetes can be optimized for small form factor and edge computing.
MicroShift is a research project that is exploring how OpenShift<sup>1</sup> Kubernetes can be optimized for small form factor and edge computing.

Edge devices deployed out in the field pose very different operational, environmental, and business challenges from those of cloud computing. These motivate different engineering trade-offs for Kubernetes at the far edge than for cloud or near-edge scenarios. Microshift's design goals cater to this:
Edge devices deployed out in the field pose very different operational, environmental, and business challenges from those of cloud computing. These motivate different engineering trade-offs for Kubernetes at the far edge than for cloud or near-edge scenarios. MicroShift's design goals cater to this:

- make frugal use of system resources (CPU, memory, network, storage, etc.),
- tolerate severe networking constraints,
- update (resp. rollback) securely, safely, speedily, and seamlessly (without disrupting workloads), and
- build on and integrate cleanly with edge-optimized OSes like Fedora IoT and RHEL for Edge, while
- providing a consistent development and management experience with standard OpenShift.

We believe these properties should also make Microshift a great tool for other use cases such as Kubernetes applications development on resource-constrained systems, scale testing, and provisioning of lightweight Kubernetes control planes.
We believe these properties should also make MicroShift a great tool for other use cases such as Kubernetes applications development on resource-constrained systems, scale testing, and provisioning of lightweight Kubernetes control planes.

Watch this [end-to-end MicroShift provisioning demo video](https://youtu.be/QOiB8NExtA4) to get a first impression of MicroShift deployed onto a [RHEL for edge computing](https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux/edge-computing) device and managed through [Open Cluster Management](https://github.com/open-cluster-management).

**Note: Microshift is still early days and moving fast. Features are missing. Things break. But you can still help shape it, too.**
**Note: MicroShift is still early days and moving fast. Features are missing. Things break. But you can still help shape it, too.**

<sup>1) more precisely [OKD](https://www.okd.io/), the Kubernetes distribution by the OpenShift community</sup>

## Minimum specs

In order to run Microshift, you will need at least:
In order to run MicroShift, you will need at least:

- 2 CPU cores
- 2GB of RAM
- ~124MB of free storage space for the Microshift binary
- ~124MB of free storage space for the MicroShift binary
- 64-bit CPU (although 32-bit is _technically_ possible, if you're up for the challenge)

For barebones development the minimum requirement is 3GB of RAM, though this can increase
if you are using resource-intensive devtools.

### OS Requirements

The all-in-one containerized Microshift can run on Windows, MacOS, and Linux.
The all-in-one containerized MicroShift can run on Windows, MacOS, and Linux.

Currently, the Microshift binary is known to be supported on the following Operating Systems:
Currently, the MicroShift binary is known to be supported on the following Operating Systems:

- Fedora 33/34
- CentOS 8 Stream
- RHEL 8
- CentOS 7
- Ubuntu 20.04

It may be possible to run Microshift on other systems, however they haven't been tested so you may run into issues.
It may be possible to run MicroShift on other systems, however they haven't been tested so you may run into issues.

## Using Microshift
## Using MicroShift

To give Microshift a try, simply install a recent test version (we don't provide stable releases yet) on a Fedora-derived Linux distro (we've only tested Fedora, RHEL, and CentOS Stream so far) using:
To give MicroShift a try, simply install a recent test version (we don't provide stable releases yet) on a Fedora-derived Linux distro (we've only tested Fedora, RHEL, and CentOS Stream so far) using:

```sh
curl -sfL https://raw.githubusercontent.com/redhat-et/microshift/main/install.sh | bash
```

This will install Microshift's dependencies (CRI-O), install it as a systemd service and start it.
This will install MicroShift's dependencies (CRI-O), install it as a systemd service and start it.

For convenience, the script will also add a new "microshift" context to your `$HOME/.kube/config`, so you'll be able to access your cluster using, e.g.:

Expand All @@ -67,21 +67,21 @@ kubectl config use-context microshift
kubectl get all -A
```

Notes: When installing Microshift on a system with an older version already installed, it is safest to remove the old data directory and start fresh:
Notes: When installing MicroShift on a system with an older version already installed, it is safest to remove the old data directory and start fresh:

```sh
rm -rf /var/lib/microshift && rm -r $HOME/.microshift
```

## [Known Issues](./docs/known-issues.md)

## Developing Microshift
## Developing MicroShift

> Note: when building or running **ARM64** container images, Linux host environments must have the `qemu-user-static` package installed. E.g. on Fedora: `dnf install qemu-user-static`.

### Building

You can locally build Microshift using one of two methods, either using a container build (recommended) on Podman or Docker:
You can locally build MicroShift using one of two methods, either using a container build (recommended) on Podman or Docker:

```sh
sudo yum -y install make golang
Expand All @@ -104,21 +104,21 @@ make

### Environment Configuration

Before running Microshift, the host must first be configured. This can be handled by running
Before running MicroShift, the host must first be configured. This can be handled by running

```
CONFIG_ENV_ONLY=true ./install.sh
```

Microshift keeps all its state in its data-dir, which defaults to `/var/lib/microshift` when running Microshift as privileged user and `$HOME/.microshift` otherwise. Note that running Microshift unprivileged only works without node role at the moment (i.e. using `--roles=controlplane` instead of the default of `--roles=controlplane,node`).
MicroShift keeps all its state in its data-dir, which defaults to `/var/lib/microshift` when running MicroShift as privileged user and `$HOME/.microshift` otherwise. Note that running MicroShift unprivileged only works without node role at the moment (i.e. using `--roles=controlplane` instead of the default of `--roles=controlplane,node`).

### Kubeconfig

When starting the Microshift for the first time the Kubeconfig file is created. If you need it for another user or to use externally the kubeadmin's kubeconfig is placed at `/var/lib/microshift/resources/kubeadmin/kubeconfig`.
When starting the MicroShift for the first time the Kubeconfig file is created. If you need it for another user or to use externally the kubeadmin's kubeconfig is placed at `/var/lib/microshift/resources/kubeadmin/kubeconfig`.

### Contributing

For more information on working with Microshift, you can find a contributor's guide in [CONTRIBUTING.md](./CONTRIBUTING.md)
For more information on working with MicroShift, you can find a contributor's guide in [CONTRIBUTING.md](./CONTRIBUTING.md)

### Community

Expand Down
2 changes: 1 addition & 1 deletion cmd/microshift/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ func main() {
func newCommand() *cobra.Command {
cmd := &cobra.Command{
Use: "microshift",
Short: "Microshift, a minimal OpenShift",
Short: "MicroShift, a minimal OpenShift",
Run: func(cmd *cobra.Command, args []string) {
cmd.Help()
os.Exit(1)
Expand Down
4 changes: 2 additions & 2 deletions docs/_config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

domain: microshift.io # if you want to force HTTPS, specify the domain without the http at the start, e.g. example.com
url: https://microshift.io # the base hostname and protocol for your site, e.g. http://example.com
title: Microshift
description: Microshift is a research project that is exploring how OpenShift Kubernetes can be optimized for small form factor and edge computing.
title: MicroShift
description: MicroShift is a research project that is exploring how OpenShift Kubernetes can be optimized for small form factor and edge computing.
type: website
keep_files: ["CNAME"]
repository: redhat-et/microshift
Expand Down
39 changes: 20 additions & 19 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,60 +6,61 @@ layout: page
toc: true
---

Microshift is a research project that is exploring how OpenShift<sup>1</sup> Kubernetes can be optimized for small form factor and edge computing.
MicroShift is a research project that is exploring how OpenShift<sup>1</sup> Kubernetes can be optimized for small form factor and edge computing.

Edge devices deployed out in the field pose very different operational, environmental, and business challenges from those of cloud computing. These motivate different engineering trade-offs for Kubernetes at the far edge than for cloud or near-edge scenarios. Microshift's design goals cater to this:
Edge devices deployed out in the field pose very different operational, environmental, and business challenges from those of cloud computing. These motivate different engineering trade-offs for Kubernetes at the far edge than for cloud or near-edge scenarios. MicroShift's design goals cater to this:

- make frugal use of system resources (CPU, memory, network, storage, etc.),
- tolerate severe networking constraints,
- update (resp. roll back) securely, safely, speedily, and seamlessly (without disrupting workloads), and
- build on and integrate cleanly with edge-optimized OSes like Fedora IoT and RHEL for Edge, while
- providing a consistent development and management experience with standard OpenShift.

We believe these properties should also make Microshift a great tool for other use cases such as Kubernetes applications development on resource-constrained systems, scale testing, and provisioning of lightweight Kubernetes control planes.
We believe these properties should also make MicroShift a great tool for other use cases such as Kubernetes applications development on resource-constrained systems, scale testing, and provisioning of lightweight Kubernetes control planes.

Watch this [end-to-end MicroShift provisioning demo video](https://youtu.be/QOiB8NExtA4) to get a first impression of MicroShift deployed onto a [RHEL for edge computing](https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux/edge-computing) device and managed through [Open Cluster Management](https://github.com/open-cluster-management).

> warning ""
> Microshift is still early days and moving fast. Features are missing. Things break. But you can still help shape it, too.
> MicroShift is still early days and moving fast. Features are missing. Things break. But you can still help shape it, too.\*\*


<sup>1) more precisely [OKD](https://www.okd.io/), the Kubernetes distribution by the OpenShift community</sup>

## Minimum specs

In order to run Microshift, you will need at least:
In order to run MicroShift, you will need at least:

- 2 CPU cores
- 2GB of RAM
- ~124MB of free storage space for the Microshift binary
- ~124MB of free storage space for the MicroShift binary
- 64-bit CPU (although 32-bit is _technically_ possible, if you're up for the challenge)

For barebones development the minimum requirement is 3GB of RAM, though this can increase
if you are using resource-intensive devtools.

### OS Requirements

The all-in-one containerized Microshift can run on Windows, MacOS, and Linux.
The all-in-one containerized MicroShift can run on Windows, MacOS, and Linux.

Currently, the Microshift binary is known to be supported on the following Operating Systems:
Currently, the MicroShift binary is known to be supported on the following Operating Systems:

- Fedora 33/34
- CentOS 8 Stream
- RHEL 8
- CentOS 7
- Ubuntu 20.04

It may be possible to run Microshift on other systems, however they haven't been tested so you may run into issues.
It may be possible to run MicroShift on other systems, however they haven't been tested so you may run into issues.

## Using Microshift
## Using MicroShift

To give Microshift a try, simply install a recent test version (we don't provide stable releases yet) on a Fedora-derived Linux distro (we've only tested Fedora, RHEL, and CentOS Stream so far) using:
To give MicroShift a try, simply install a recent test version (we don't provide stable releases yet) on a Fedora-derived Linux distro (we've only tested Fedora, RHEL, and CentOS Stream so far) using:

```sh
curl -sfL https://raw.githubusercontent.com/redhat-et/microshift/main/install.sh | bash
```

This will install Microshift's dependencies (CRI-O), install it as a systemd service and start it.
This will install MicroShift's dependencies (CRI-O), install it as a systemd service and start it.

For convenience, the script will also add a new "microshift" context to your `$HOME/.kube/config`, so you'll be able to access your cluster using, e.g.:

Expand All @@ -75,22 +76,22 @@ kubectl get all -A
```

> info ""
> When installing Microshift on a system with an older version already installed, it is safest to remove the old data directory and start fresh:
> When installing MicroShift on a system with an older version already installed, it is safest to remove the old data directory and start fresh:

```sh
rm -rf /var/lib/microshift && rm -r $HOME/.microshift
```

## [Known Issues](./known-issues.md)

## Developing Microshift
## Developing MicroShift

> warning ""
> when building or running **ARM64** container images, Linux host environments must have the `qemu-user-static` package installed. E.g. on Fedora: `dnf install qemu-user-static`.

### Building

You can locally build Microshift using one of two methods, either using a container build (recommended) on Podman or Docker:
You can locally build MicroShift using one of two methods, either using a container build (recommended) on Podman or Docker:

```sh
sudo yum -y install make golang
Expand All @@ -113,21 +114,21 @@ make

### Environment Configuration

Before running Microshift, the host must first be configured. This can be handled by running
Before running MicroShift, the host must first be configured. This can be handled by running

```sh
CONFIG_ENV_ONLY=true ./install.sh
```

Microshift keeps all its state in its data-dir, which defaults to `/var/lib/microshift` when running Microshift as privileged user and `$HOME/.microshift` otherwise. Note that running Microshift unprivileged only works without node role at the moment (i.e. using `--roles=controlplane` instead of the default of `--roles=controlplane,node`).
MicroShift keeps all its state in its data-dir, which defaults to `/var/lib/microshift` when running MicroShift as privileged user and `$HOME/.microshift` otherwise. Note that running MicroShift unprivileged only works without node role at the moment (i.e. using `--roles=controlplane` instead of the default of `--roles=controlplane,node`).

### Kubeconfig

When starting the Microshift for the first time the Kubeconfig file is created. If you need it for another user or to use externally the kubeadmin's kubeconfig is placed at `/var/lib/microshift/resources/kubeadmin/kubeconfig`.
When starting the MicroShift for the first time the Kubeconfig file is created. If you need it for another user or to use externally the kubeadmin's kubeconfig is placed at `/var/lib/microshift/resources/kubeadmin/kubeconfig`.

### Contributing

For more information on working with Microshift, you can find a contributor's guide in [CONTRIBUTING.md](https://github.com/redhat-et/microshift/blob/main/CONTRIBUTING.md)
For more information on working with MicroShift, you can find a contributor's guide in [CONTRIBUTING.md](./CONTRIBUTING.md)

### Community

Expand Down
4 changes: 2 additions & 2 deletions docs/microshift-aio/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ tags: all-in-one, aio
toc: true
---

## Run Microshift All-In-One as a Systemd Service
## Run MicroShift All-In-One as a Systemd Service

Copy `microshift-aio` unit file to `/etc/systemd` and the aio run script to `/usr/bin`

Expand Down Expand Up @@ -130,4 +130,4 @@ make microshfit-aio
## Limitation

These instructions are tested on Linux, Mac, and Windows.
On MacOS, running containerized Microshift as non-root is not supported on MacOS.
On MacOS, running containerized MicroShift as non-root is not supported on MacOS.
6 changes: 3 additions & 3 deletions hack/all-in-one/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Containerized Microshift With GPU Support and Kubectl
# Containerized MicroShift With GPU Support and Kubectl

## Run Microshift All-In-One as a Systemd Service
## Run MicroShift All-In-One as a Systemd Service

Copy microshift-aio unit file to /etc/systemd and the aio run script to /usr/bin

Expand Down Expand Up @@ -109,4 +109,4 @@ TAG="quay.io/myname/myrepo:dev" ./hack/build-aio-dev.sh
## Limitation

These instructions are tested on Linux, Mac, and Windows.
On MacOS, running containerized Microshift as non-root is not supported on MacOS.
On MacOS, running containerized MicroShift as non-root is not supported on MacOS.
4 changes: 2 additions & 2 deletions install.sh
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,7 @@ install_crio() {
}


# CRI-O config to match Microshift networking values
# CRI-O config to match MicroShift networking values
crio_conf() {
sudo sh -c 'cat << EOF > /etc/cni/net.d/100-crio-bridge.conf
{
Expand Down Expand Up @@ -195,7 +195,7 @@ get_microshift() {

cat << EOF | sudo tee /usr/lib/systemd/system/microshift.service
[Unit]
Description=Microshift
Description=MicroShift
After=crio.service

[Service]
Expand Down
2 changes: 1 addition & 1 deletion packaging/images/microshift-aio/unit
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
[Unit]
Description=Microshift
Description=MicroShift
After=crio.service

[Service]
Expand Down
Loading