Skip to content

Commit

Permalink
Formatting and content updates for README.md
Browse files Browse the repository at this point in the history 
- Consistent use of Markdown headings: children of an h1 heading should be
  h2 headings
- Consistent line wrapping: previously, some paragraphs were line-wrapped
  and others were not. This commit makes all paragraphs unwrapped.
- Use `pip` for installation rather than `python setup.py`
- Make it easier to copy-and-paste most command examples by removing `$`
  shell prompts
- Remove unnecessary `GRANT` commands from mysql instructions: `%` is a
  wildcard so `'esi_leap'@'%'` already grants access to
  `'esi_leap'@'<database_ip>'`
- Simplify the "Container Installation" section
  • Loading branch information
@larsks
larsks committed Jun 27, 2024
1 parent 182b188 commit de9d939
Showing 1 changed file with 42 additions and 67 deletions.
109 changes: 42 additions & 67 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,68 +1,54 @@
# esi-leap

esi-leap is an OpenStack service for leasing baremetal nodes, designed to run
on top of [multi-tenant
Ironic](https://docs.openstack.org/ironic/latest/admin/node-multitenancy.html).
It consists of an API that provides endpoints for leasing operations and a
manager service that updates the status of leases and offers as required. See
the [documentation](https://esi.readthedocs.io/en/latest/index.html) for
more info on ESI.
esi-leap is an OpenStack service for leasing baremetal nodes, designed to run on top of [multi-tenant Ironic](https://docs.openstack.org/ironic/latest/admin/node-multitenancy.html). It consists of an API that provides endpoints for leasing operations and a manager service that updates the status of leases and offers as required. See the [documentation](https://esi.readthedocs.io/en/latest/index.html) for more info on ESI.


### Installation
## Installation

To install as a package:
- `pip install esi-leap`

To install from source:

```
$ git clone https://github.com/CCI-MOC/esi-leap
$ cd esi-leap
$ sudo python setup.py install
pip install esi-leap
```

To install from source:

### Client
```
git clone https://github.com/CCI-MOC/esi-leap
cd esi-leap
pip install .
```

esi-leap has a command line client which can be found here:
https://github.com/CCI-MOC/python-esileapclient
## Client

esi-leap has a command line client which can be found here: https://github.com/CCI-MOC/python-esileapclient

### Create the esi-leap Database
## Create the esi-leap Database

The esi-leap service requires a database to store its information. To set this
up using the MySQL database used by other OpenStack services, run the following
commands, replacing \<PASSWORD\> with a suitable password and \<DATABASE\_IP\>
with the IP address of your MySQL database (if you're not sure, use localhost
or 127.0.0.1).
The esi-leap service requires a database to store its information. To set this up using the MySQL database used by other OpenStack services, run the following commands, replacing `<PASSWORD>` with a suitable password and `<DATABASE_IP>` with the IP address of your MySQL database (if you're not sure, use `localhost` or `127.0.0.1`).

```
$ mysql -u root -p
mysql> CREATE USER 'esi_leap'@'<DATABASE_IP>' IDENTIFIED BY '<PASSWORD>';
mysql> CREATE USER 'esi_leap'@'%' IDENTIFIED BY '<PASSWORD>';
mysql> CREATE DATABASE esi_leap CHARACTER SET utf8;
mysql> GRANT ALL PRIVILEGES ON esi_leap.* TO 'esi_leap'@'<DATABASE_IP>';
mysql> GRANT ALL PRIVILEGES ON esi_leap.* TO 'esi_leap'@'%';
mysql> FLUSH PRIVILEGES;
$ mysql -u root -p
mysql> CREATE USER 'esi_leap'@'%' IDENTIFIED BY '<PASSWORD>';
mysql> CREATE DATABASE esi_leap CHARACTER SET utf8;
mysql> GRANT ALL PRIVILEGES ON esi_leap.* TO 'esi_leap'@'%';
mysql> FLUSH PRIVILEGES;
```

If you use this method, the resulting database connection string should be:

```
mysql+pymysql://esi_leap:PASSWORD@DATABASE_IP/esi_leap
mysql+pymysql://esi_leap:PASSWORD@DATABASE_IP/esi_leap
```


### Configuration
## Configuration

Run the following commands to generate the configuration file and copy it to
the right place:

```
$ tox -egenconfig
$ sudo mkdir /etc/esi-leap
$ sudo cp etc/esi-leap/esi-leap.conf.sample /etc/esi-leap/esi-leap.conf
tox -egenconfig
sudo mkdir /etc/esi-leap
sudo cp etc/esi-leap/esi-leap.conf.sample /etc/esi-leap/esi-leap.conf
```

Edit `/etc/esi-leap/esi-leap.conf` with the proper values. (see sample config
Expand Down Expand Up @@ -120,58 +106,49 @@ password = <ironic password>
dummy_node_dir=/tmp/nodes
```


### Create the OpenStack Service
## Create the OpenStack Service

```
$ openstack user create --domain default --password-prompt esi-leap
$ openstack role add --project service --user esi-leap admin
$ openstack service create --name esi-leap lease
$ openstack endpoint create esi-leap --region RegionOne public http://<YOUR_IP>:7777
openstack user create --domain default --password-prompt esi-leap
openstack role add --project service --user esi-leap admin
openstack service create --name esi-leap lease
openstack endpoint create esi-leap --region RegionOne public http://<YOUR_IP>:7777
```

## Run the Services

### Run the Services

Start by instantiating the database:
Start by creating the database schema:

```
$ sudo esi-leap-dbsync create_schema
esi-leap-dbsync create_schema
```

Once that's done, you can run the manager and API services:


```
$ sudo esi-leap-manager
$ sudo esi-leap-api
esi-leap-manager
esi-leap-api
```

### Installation using Containerization

By encapsulating the ESI Leap into a container, all the necessary dependencies, configurations and services are bundled into a single package.
## Container Installation

Please make sure to follow the instructions in the [Configuration](#configuration) section to generate the esi-leap.conf file.

Make sure to follow the instructions in the [Create Openstack Service](#create-the-openstack-service) to create the OpenStack service and endpoint.

After that build the container image using the podman build command, as Containerfile is located in the current directory. The syntax is as follows:
You can build an `esi-leap` container using the included `Containerfile`:

```
$ podman build -t <image-name> -f Containerfile .
podman build -t esi-leap .
```

Once the container image is built, you can run it using the podman run command. The syntax is as follows:
Once the container image has been built, you can run it using the `podman run` command. First, make sure you have created an appropriate configuration file following the instructions in the [Configuration](#configuraiton) section, and ensure you have added the appropriate service and endpoint to your OpenStack environment as described in [Create the OpenStack Service](#create-the-openstack-service). Then you can run the image like this:

```
$ podman run --name <container-name> -p <host-port>:<container-port> -d -v <path-to-esi-leap.conf-file>:/etc/esi-leap <image-name>
podman run --name <container-name> -p <host-port>:<container-port> -d \
-v <path-to-esi-leap.conf-file>:/etc/esi-leap/esi-leap.conf esi-leap
```

## Using Dummy Nodes

### Using Dummy Nodes

If you wish to use dummy nodes instead of Ironic nodes, simply specify the `dummy_node_dir`
as specified above. Once you do so, add dummy nodes as follows:
If you wish to use dummy nodes instead of Ironic nodes, simply specify the `dummy_node_dir` as specified above. Once you do so, add dummy nodes as follows:

```
cat <<EOF > /tmp/nodes/1718
Expand All @@ -189,6 +166,4 @@ cat <<EOF > /tmp/nodes/1718
EOF
```

`1718` is the dummy node UUID; replace it with whatever you'd like. When creating an offer
for this dummy node, simply specify `resource_type` as `dummy_node` and `resource_uuid` as
`1718`.
`1718` is the dummy node UUID; replace it with whatever you'd like. When creating an offer for this dummy node, simply specify `resource_type` as `dummy_node` and `resource_uuid` as `1718`.

0 comments on commit de9d939

Please sign in to comment.