vpc-img-inst 1.0.0b13
vpc-img-inst is a lightweight script for quick-and-dirty generation of custom VSI images by installing features (software bundles) on base images.
Requires Python: >=3.6

# Image Installer For IBM-VPC

`vpc-img-inst` is a lightweight script for quick-and-dirty generation of custom VSI images by installing features (software bundles) on base images.  
For an overview and a quick start consider reading our [blog](https://medium.com/@erezh/how-to-get-ibm-vpc-images-with-cuda-and-other-features-easily-6786127ab4e5).

## Setup

Mostly tested with Fedora 35/37 and Ubuntu 20/22, but should work with most Linux and Mac systems.   
#### Requirements
- `ssh-keygen` utility - available as part of the Open SSH client.
- Python3.

#### Installation
Run: `pip install vpc-img-inst`  
Following installation, a directory containing various scripts will be created in  `~/.vpc-img-inst`.   
#### Upgrading
When upgrading to a newer version, to get an updated version of the scripts, it's important the keep the following points in mind:
- Delete `~/.vpc-img-inst`, as existing directories won't be replaced to avoid overwriting user scripts. 
- Upgrade using the following flags: `pip install --no-cache-dir -U vpc-img-inst`.  
Technical reasoning: for the tool to execute commands post the pip install phase, `whl` files can't be used, instead opting to use the downloaded `tar` instead.

## Usage
- Create a new custom image:
```
vpc-img-inst [--iam-api-key IAM_API_KEY] [--region REGION] [-o OUTPUT_FOLDER] [-f FEATURE] [-im BASE_IMAGE_NAME] [-it INSTALLATION_TYPE] [--compute-iam-endpoint IAM_ENDPOINT] [-y] 
[--cleanup PATH_TO_RESOURCES_FILE][--version] [--help]
```
```vpc-img-inst --help```
### Examples
- `vpc-img-inst -a <API_KEY> -y -f cuda -it rhel -im ibm-redhat-8-6`  
Create a custom image of CUDA on RHEL 8.6
- `vpc-img-inst -a <API_KEY> -y -f docker -f cuda -it ubuntu` (using default base image)  
Create a custom image of Docker and CUDA on Ubuntu (default 22.4) 
- `vpc-img-inst --help`  
Get a short description of the available flags via  
- `vpc-img-inst -c <PATH_TO_FILE>`  
Clean-up a previously failed execution (see [Cleanup](##-Clean-up))

### Flags Detailed Description
Note - Flag values are case sensitive.  
For example `--feature cuda` !=  `--feature CUDA`.

<!--- <img width=125/> is used in the following table to create spacing --->
 |<span style="color:orange">Key|<span style="color:orange">Default|<span style="color:orange">Mandatory|<span style="color:orange">Additional info|
 |---|---|---|---|
 | iam-api-key   | NA|yes|IBM Cloud API key. To generate a new API Key adhere to the following [guide](https://www.ibm.com/docs/en/spectrumvirtualizecl/8.1.3?topic=installing-creating-api-key)
 | output-folder   |/temp/<auto-generated-folder>/logs/ | no |Path to folder storing IDs of resources created by this program and installation logs |
 | version       | NA| no |Returns vpc-img-inst's package version|
 |region| eu-de| no|Geographical location for deployment and scope for available resources by the IBM-VPC service. Regions are listed <a href="https://cloud.ibm.com/docs/vpc?topic=vpc-creating-a-vpc-in-a-different-region&interface=cli"> here</a>. |
 |base-image-name| ibm-ubuntu-22-04-4-minimal-amd64-2| no| Prefix of an image name from your account, on which the produced image will be based. Could be either an IBM stock image as explained [here](https://cloud.ibm.com/docs/vpc?topic=vpc-about-images) or a custom image.|
  | installation-type| ubuntu | no |type of installation to use, e.g. for feature cuda the currently supported types are: ubuntu and rhel.|
  | feature| cuda | no |Feature to install on the produced image. Currently supporting: cuda and docker.|
  | cleanup| NA | no |Path to a resources file, that will be submitted for deletion. Program will be terminated subsequently.|
 compute_iam_endpoint|https://iam.cloud.ibm.com|no|Alternative IAM endpoint url for the cloud provider, e.g. https://iam.test.cloud.ibm.com|


## Extendability
To extend the features/installation types this program support, please follow the next steps:
1. To add a new feature, inside `~/.vpc-img-inst`, create a folder named after the feature in camel case format, e.g nodeJS.
2. to add new installation type, inside a feature's folder add a new installation type by adding a script with the following naming format: `install_<FeatureName>_<installation_type>.sh`, e.g. "install_cuda_ubuntu.sh".


## Clean-up
All resources created during the execution of the program will be automatically removed and unregistered from the IBM-VPC (apart from the created image). This process also takes place upon a failed run. 
#### Manual clean-up
To manually remove byproduct resources run: `vpc-img-inst -c <path_to_resources_file>`.  
Users may have to resort to running this command in the odd occasion where this program fails to remove its byproducts.   
The path to the resources file is printed at the start of the execution.

## Execution Example
![](doc_assets/example.png?raw=true)