From 1f766e707c1bc181809bde969d318c7c832a8f5b Mon Sep 17 00:00:00 2001
From: Francisco Mendonca <francisco.mendonca@hesge.ch>
Date: Mon, 23 Sep 2024 15:56:17 +0200
Subject: [PATCH] Updated README - New readme + man page for python tool
---
README.md | 97 +++++++++++++++++++++++-------------------------
lab-os-python.md | 72 +++++++++++++++++++++++++++++++++++
2 files changed, 119 insertions(+), 50 deletions(-)
create mode 100644 lab-os-python.md
diff --git a/README.md b/README.md
index e81338c..02252eb 100644
--- a/README.md
+++ b/README.md
@@ -1,72 +1,69 @@
-# Lab-OS-Python
+# OpenStack's Python CLI
-This is a boilerplate that replicates the exercise done in the [Lab-OS-CLI](https://githepia.hesge.ch/lsds/teaching/bachelor/cloud-and-deployment/lab-os-cli).
+OpenStack provides a Python SDK that simplifies interactions with OpenStack cloud services. This tutorial will guide you through the installation of the SDK, creating a connection to your OpenStack cloud, and managing virtual machines (VMs) using the Python CLI.
-## NAME
-**lab-os** - Python script to manage OpenStack Virtual Machines
+## Installation
-## SYNOPSIS
-`lab-os.py` [**create**|**destroy**|**start**|**stop**|**snapshot**]
+To get started, you need to install the OpenStack SDK. This can be done easily with `pip`, the Python package installer. Run the following command in your terminal:
-## DESCRIPTION
-`lab-os.py` is a Python script designed to help manage OpenStack Virtual Machines with simple commands.
+```bash
+pip install openstacksdk
+```
-## OPTIONS
+This command fetches the OpenStack SDK from the Python Package Index (PyPI) and installs it on your system.
-### **create**
-Create a new virtual machine. This command returns a unique **ID** that can be used to manage the VM in subsequent commands.
+## Creating a connection
-### **destroy ID**
-Destroy an existing virtual machine using the provided **ID**.
+Once the SDK is installed, you can establish a connection to your OpenStack cloud. You can do this using a single line of code if your environment is set up correctly, or you can specify all the necessary parameters explicitly. Here's how you can create a connection:
-### **start ID**
-Start a virtual machine using the provided **ID**.
+```python
+conn = openstack.connect(engine='engines')
+
+# or
+
+conn = openstack.connect(
+ auth_url="https://keystone.cloud.switch.ch:5000/v3",
+ project_name="<YOUR PROJECT NAME>",
+ username="<YOUR USERNAME>",
+ password="<YOUR PASSWORD>",
+ region_name="ZH",
+ domain_name='default',
+ version='2'
+ )
+```
-### **stop ID**
-Stop a running virtual machine using the provided **ID**.
+In the first example, `engine='engines'` assumes that you have your cloud configuration defined in an environment variable or a configuration file. In the second example, you are explicitly providing the authentication URL, project name, username, password, region name, and other parameters needed for the connection.
-### **snapshot ID**
-Create a snapshot of the current state of the virtual machine using the provided **ID**. This command also returns a unique **ID** for the snapshot.
+Make sure to replace `<YOUR PROJECT NAME>`, `<YOUR USERNAME>`, and `<YOUR PASSWORD>` with your actual credentials. This connection will allow you to interact with various OpenStack services.
-## EXAMPLES
+## VM Management
-### Create a new virtual machine:
-```python
-# Run the Python script to create a VM
-python lab-os.py create
-```
-This will return a unique ID for the newly created virtual machine.
+After establishing a connection, you can manage virtual machines in your OpenStack environment. Below is an example of how to create a new VM:
-### Start a virtual machine:
```python
-# Start the virtual machine using the returned ID
-python lab-os.py start <ID>
+server = conn.compute.create_server(
+ name='Openstack-Instance',
+ image_id='856becdd-3df9-488e-af98-871b98624b2c', # From: https://engines.switch.ch/horizon/project/images
+ flavor_id='2', # 2 = m1.small. Use: openstack --os-cloud <cloud-name/normally is engines> flavor list
+ networks=[{"uuid": 'c34c17a4-341e-463e-ab52-eed4817387ad'}] # From: https://engines.switch.ch/horizon/project/networks/, select the network you want to use, and retrieve the ID
+)
```
-This starts the virtual machine associated with the provided **ID**.
-### Stop a virtual machine:
-```python
-# Stop the virtual machine using the returned ID
-python lab-os.py stop <ID>
-```
-This stops the virtual machine associated with the provided **ID**.
+In this code snippet:
-### Create a snapshot of a virtual machine:
-```python
-# Create a snapshot using the VM ID
-python lab-os.py snapshot <ID>
-```
-This creates a snapshot of the virtual machine associated with the provided **ID** and returns a unique **ID** for the snapshot.
+- `name` specifies the name of the VM you want to create.
+- `image_id` is the identifier for the image you want to use; you can find available images in your OpenStack dashboard under the images section.
+- `flavor_id` refers to the VM flavor, which determines the resources allocated to the VM. You can list available flavors by using the OpenStack CLI command.
+- `networks` is a list of networks that the VM will connect to, specified by their UUIDs, which can also be found in the OpenStack dashboard.
+
+Once the server is created, you may want to delete it later. Here’s how you can do that:
-### Destroy a virtual machine:
```python
-# Destroy the virtual machine using the returned ID
-python lab-os.py destroy <ID>
+conn.compute.delete_server(server)
```
-This destroys the virtual machine associated with the provided **ID**.
-## AUTHOR
-Written by Francisco Mendonca.
+This line of code will delete the VM you created earlier. Make sure to manage your resources effectively to avoid unnecessary charges.
+
+With this setup, you can start using the OpenStack Python SDK to automate your cloud infrastructure management tasks.
-## COPYRIGHT
-This is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License.
+To find out more about OpenStack's Python SDK, visit [this page](https://docs.openstack.org/openstacksdk/latest/user/index.html).
\ No newline at end of file
diff --git a/lab-os-python.md b/lab-os-python.md
new file mode 100644
index 0000000..e81338c
--- /dev/null
+++ b/lab-os-python.md
@@ -0,0 +1,72 @@
+# Lab-OS-Python
+
+This is a boilerplate that replicates the exercise done in the [Lab-OS-CLI](https://githepia.hesge.ch/lsds/teaching/bachelor/cloud-and-deployment/lab-os-cli).
+
+## NAME
+**lab-os** - Python script to manage OpenStack Virtual Machines
+
+## SYNOPSIS
+`lab-os.py` [**create**|**destroy**|**start**|**stop**|**snapshot**]
+
+## DESCRIPTION
+`lab-os.py` is a Python script designed to help manage OpenStack Virtual Machines with simple commands.
+
+## OPTIONS
+
+### **create**
+Create a new virtual machine. This command returns a unique **ID** that can be used to manage the VM in subsequent commands.
+
+### **destroy ID**
+Destroy an existing virtual machine using the provided **ID**.
+
+### **start ID**
+Start a virtual machine using the provided **ID**.
+
+### **stop ID**
+Stop a running virtual machine using the provided **ID**.
+
+### **snapshot ID**
+Create a snapshot of the current state of the virtual machine using the provided **ID**. This command also returns a unique **ID** for the snapshot.
+
+## EXAMPLES
+
+### Create a new virtual machine:
+```python
+# Run the Python script to create a VM
+python lab-os.py create
+```
+This will return a unique ID for the newly created virtual machine.
+
+### Start a virtual machine:
+```python
+# Start the virtual machine using the returned ID
+python lab-os.py start <ID>
+```
+This starts the virtual machine associated with the provided **ID**.
+
+### Stop a virtual machine:
+```python
+# Stop the virtual machine using the returned ID
+python lab-os.py stop <ID>
+```
+This stops the virtual machine associated with the provided **ID**.
+
+### Create a snapshot of a virtual machine:
+```python
+# Create a snapshot using the VM ID
+python lab-os.py snapshot <ID>
+```
+This creates a snapshot of the virtual machine associated with the provided **ID** and returns a unique **ID** for the snapshot.
+
+### Destroy a virtual machine:
+```python
+# Destroy the virtual machine using the returned ID
+python lab-os.py destroy <ID>
+```
+This destroys the virtual machine associated with the provided **ID**.
+
+## AUTHOR
+Written by Francisco Mendonca.
+
+## COPYRIGHT
+This is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License.
--
GitLab