|
| 1 | +# MC-Infra-Manager Initialization Sub Command Guide |
| 2 | + |
| 3 | +## Overview |
| 4 | +Added a new `infra-init` command under the `setup` subcommand to automatically initialize MC-Infra-Manager with the currently running version. This feature ensures version compatibility and provides a streamlined initialization process for registering multi-cloud connection information and common resources. |
| 5 | + |
| 6 | +## Prerequisites and Reference Information |
| 7 | +This feature is an experimental add-on designed to make the `Initialize MC-Infra-Manager to configure Multi-Cloud info` process more stable and convenient after all infrastructure has been built using the `./mcc infra run` command. |
| 8 | + |
| 9 | +The essential file required to properly execute the `infra-init` command is an encrypted credential file, which is created through the following CB-Tumblebug process: |
| 10 | +``` |
| 11 | +👉 Create your cloud credentials: |
| 12 | + ./init/genCredential.sh |
| 13 | + → Then edit ~/.cloud-barista/credentials.yaml with your CSP info. |
| 14 | +
|
| 15 | +👉 Encrypt the credentials file: |
| 16 | + ./init/encCredential.sh |
| 17 | +``` |
| 18 | + |
| 19 | +If the above method does not create the file properly or if you need detailed information about the MC-Infra-Manager initialization process, please refer to the [CB-Tumblebug Multi-Cloud Configuration Guide](https://github.com/cloud-barista/cb-tumblebug?tab=readme-ov-file#3-initialize-cb-tumblebug-to-configure-multi-cloud-info) documentation. |
| 20 | + |
| 21 | +Additionally, since CB-Tumblebug (used by MC-Infra-Manager) uses uv internally, it is recommended to install uv in advance. |
| 22 | +``` |
| 23 | +curl -LsSf https://astral.sh/uv/install.sh | sh |
| 24 | +source $HOME/.local/bin/env |
| 25 | +``` |
| 26 | +For more detailed information, please refer to the CB-Tumblebug documentation. |
| 27 | + |
| 28 | +The `infra-init` command must be executed with the user account added to the Docker group to run mcc without sudo. |
| 29 | +``` |
| 30 | +$ sudo usermod -aG docker $USER |
| 31 | +$ newgrp docker |
| 32 | +``` |
| 33 | + |
| 34 | +## Key Features |
| 35 | + |
| 36 | +1. **Execution Status Check**: Verify if MC-Infra-Manager is running |
| 37 | +2. **Version Check**: Check the currently running MC-Infra-Manager version (from docker compose ps or docker-compose.yaml) |
| 38 | +3. **Health Status Check**: Verify if MC-Infra-Manager is in healthy state |
| 39 | +4. **Guidance Message**: Provide related information and procedure guidance after version confirmation |
| 40 | +5. **User Confirmation**: Confirm preparation of encrypted credential files |
| 41 | +6. **MC-Infra-Manager Folder Check**: Check the exact Git tag (version) state of existing cb-tumblebug folder |
| 42 | +7. **Smart Version Management**: Differentiated processing based on Git checkout state |
| 43 | +8. **Intuitive Menu System**: Provide optimized selection options for each situation |
| 44 | +9. **Download**: Download the version matching the currently running MC-Infra-Manager from GitHub (CB-Tumblebug repository) |
| 45 | +10. **Execution Guidance**: Display information about the folder to be executed |
| 46 | +11. **Initialization**: Execute init.sh to register multi-cloud connection information and common resources (with user input support) |
| 47 | +12. **Return**: Return to the original working directory |
| 48 | + |
| 49 | +## Enhanced Capabilities |
| 50 | + |
| 51 | +### 1. Health Status Validation |
| 52 | +- Checks if MC-Infra-Manager container is in healthy state before proceeding |
| 53 | +- Prevents initialization attempts on unstable containers |
| 54 | +- Provides clear guidance when container is not ready |
| 55 | +- Suggests using `./mcc infra info` to check system status |
| 56 | + |
| 57 | +### 2. Advanced Git Version Management |
| 58 | +- **Precise Tag State Verification**: Verify that the current HEAD points exactly to a tag using `git describe --exact-match HEAD` |
| 59 | +- **Git Checkout Functionality**: Switch to the desired version using `git checkout` command |
| 60 | +- **Tag Existence Check**: Verify that the desired tag exists in the repository |
| 61 | + |
| 62 | +### 3. Smart Directory Handling |
| 63 | +- **Same Version (Exact Tag Checkout)**: |
| 64 | + ``` |
| 65 | + 1. Delete and download fresh |
| 66 | + 2. Use existing files |
| 67 | + 0. Exit |
| 68 | + ``` |
| 69 | + |
| 70 | +- **Different Version or Tag Not Checked Out**: |
| 71 | + ``` |
| 72 | + 1. Delete and download fresh |
| 73 | + 2. Switch to current version and continue initialization |
| 74 | + 3. Switch to current version and exit |
| 75 | + 0. Exit |
| 76 | + ``` |
| 77 | + |
| 78 | +### 4. User Experience Improvements |
| 79 | +- **Clear Guidance Messages**: Provide specific explanations for each situation |
| 80 | +- **Git Command Guide**: Present manual resolution methods |
| 81 | +- **English Interface**: All messages unified in English |
| 82 | +- **Intuitive Menu**: Improve user experience with number-based selection |
| 83 | +- **MC-Infra-Manager Terminology**: All user-facing messages use MC-Infra-Manager instead of CB-Tumblebug |
| 84 | + |
| 85 | +## Technical Implementation |
| 86 | + |
| 87 | +### New Functions Added |
| 88 | +- `isInfraManagerRunning()`: Container running status validation |
| 89 | +- `isInfraManagerHealthy()`: Container health status validation |
| 90 | +- `getCurrentInfraManagerVersion()`: Get current running version from docker compose or docker-compose.yaml |
| 91 | +- `getVersionFromDockerCompose()`: Extract version from running docker compose ps output |
| 92 | +- `getVersionFromDockerComposeFile()`: Extract version from docker-compose.yaml file |
| 93 | +- `getExistingTumblebugVersion()`: Precise Git tag state checking |
| 94 | +- `isTagExistsInRepo()`: Tag existence verification |
| 95 | +- `showMenuAndHandleChoice()`: Context-aware menu system |
| 96 | +- `switchToVersion()`: Git checkout functionality |
| 97 | +- `downloadAndInitTumblebug()`: Download and initialize MC-Infra-Manager |
| 98 | +- `initializeTumblebug()`: Execute init.sh script |
| 99 | + |
| 100 | +### Error Handling |
| 101 | +- Graceful handling of Git repository issues |
| 102 | +- Clear error messages with resolution guidance |
| 103 | +- Automatic directory restoration on errors |
| 104 | +- Proper error return to original directory even on failure |
| 105 | + |
| 106 | +### Initialization Process |
| 107 | +- Creates a temporary bash script for isolated execution |
| 108 | +- Changes to cb-tumblebug directory |
| 109 | +- Executes `init/init.sh` directly (setup.env is currently commented out) |
| 110 | +- Proper stdin/stdout/stderr handling for user input during initialization |
| 111 | + |
| 112 | +## Usage |
| 113 | + |
| 114 | +```bash |
| 115 | +# Basic usage |
| 116 | +./mcc setup infra-init |
| 117 | + |
| 118 | +# The command will: |
| 119 | +# 1. Check if MC-Infra-Manager is running and healthy |
| 120 | +# 2. Detect the current running version |
| 121 | +# 3. Validate existing directory Git state |
| 122 | +# 4. Provide appropriate options based on the situation |
| 123 | +# 5. Execute initialization with proper version matching |
| 124 | +``` |
| 125 | + |
| 126 | +## Benefits |
| 127 | + |
| 128 | +1. **Version Safety**: Ensures exact version compatibility between running container and initialization script |
| 129 | +2. **User Convenience**: Automated version detection and management |
| 130 | +3. **Flexibility**: Multiple options for different scenarios |
| 131 | +4. **Reliability**: Health checks and proper error handling |
| 132 | +5. **Maintainability**: Clean, modular code structure |
| 133 | +6. **Multi-Cloud Setup**: Registers multi-cloud connection information and common resources (CSP credentials, specs, images, etc.) |
| 134 | + |
| 135 | +## Example Scenarios |
| 136 | + |
| 137 | +### Scenario 1: Fresh Installation |
| 138 | +```bash |
| 139 | +[MC-Infra-Manager Initialization] |
| 140 | + |
| 141 | +✅ MC-Infra-Manager is running. |
| 142 | +Checking MC-Infra-Manager execution version... |
| 143 | +✅ Version confirmed: 0.11.21 |
| 144 | +✅ MC-Infra-Manager is healthy. |
| 145 | + |
| 146 | +[ Important Notice ] |
| 147 | +MC-Infra-Manager v0.11.21 version is running. |
| 148 | +Encrypted credential files must be prepared before running MC-Infra-Manager initialization. |
| 149 | + |
| 150 | +Downloading MC-Infra-Manager v0.11.21 version from GitHub... |
| 151 | +Target directory: /home/ubuntu/go/src/github.com/cloud-barista/cb-tumblebug |
| 152 | +``` |
| 153 | + |
| 154 | +### Scenario 2: Existing Directory with Wrong Version |
| 155 | +```bash |
| 156 | +Different version of MC-Infra-Manager found in /home/ubuntu/go/src/github.com/cloud-barista/cb-tumblebug folder. |
| 157 | +Current running version: v0.11.21 |
| 158 | +Existing directory version: v0.11.18 |
| 159 | +The running version (v0.11.21) exists in the repository but is not currently checked out. |
| 160 | + |
| 161 | +Please select an option: |
| 162 | +1. Delete and download fresh |
| 163 | +2. Switch to current version and continue initialization |
| 164 | +3. Switch to current version and exit |
| 165 | +0. Exit |
| 166 | +Enter your choice (0-3): |
| 167 | +``` |
| 168 | +
|
| 169 | +### Scenario 3: MC-Infra-Manager Not Running |
| 170 | +```bash |
| 171 | +[MC-Infra-Manager Initialization] |
| 172 | + |
| 173 | +❌ MC-Infra-Manager is not running. |
| 174 | +Please start the M-CMP system first: |
| 175 | + ./mcc infra run |
| 176 | + |
| 177 | +Please try again after the system is running. |
| 178 | +``` |
| 179 | +
|
| 180 | +### Scenario 4: MC-Infra-Manager Not Healthy |
| 181 | +```bash |
| 182 | +[MC-Infra-Manager Initialization] |
| 183 | + |
| 184 | +✅ MC-Infra-Manager is running. |
| 185 | +Checking MC-Infra-Manager execution version... |
| 186 | +✅ Version confirmed: 0.11.21 |
| 187 | +❌ MC-Infra-Manager is not healthy yet. |
| 188 | +Please wait for MC-Infra-Manager to become healthy and try again: |
| 189 | + ./mcc infra info |
| 190 | + |
| 191 | +Please try again after MC-Infra-Manager becomes healthy. |
| 192 | +``` |
| 193 | +
|
| 194 | +## Troubleshooting |
| 195 | +
|
| 196 | +### API Password Configuration |
| 197 | +If MC-Infra-Manager's API Password(`TB_API_PASSWORD`) is not set, the string value `"default"` is used as the password, so no error occurs. However, if MC-Infra-Manager is running with a custom API Password, the API Password between the downloaded version and the running version may not match, which can cause errors. |
| 198 | +
|
| 199 | +Therefore, when executing the `./mcc setup infra-init` command, if an `Unauthorized` error occurs as shown below, please check the `TB_API_PASSWORD` configuration value: |
| 200 | +
|
| 201 | +``` |
| 202 | +"Error during resource loading: 401 Client Error: Unauthorized for url: http://localhost:1323/tumblebug/loadAssets" |
| 203 | +``` |
| 204 | +
|
| 205 | +MC-Infra-Manager API Password uses Hash verification method. For detailed information, please refer to the [TB API Password Configuration Guide](https://github.com/cloud-barista/cb-tumblebug/tree/main/cmd/bcrypt) documentation. |
| 206 | +
|
| 207 | +In mc-admin-cli's `./conf/docker/docker-compose.yaml` file, the `mc-infra-manager` service is defined, and the `TB_API_PASSWORD` environment variable can be set in the `environment` section. |
| 208 | +For the current CB-Tumblebug (used by MC-Infra-Manager), if the `TB_API_PASSWORD` environment variable is not set, the string `default` is used as the `TB_API_PASSWORD` value. |
| 209 | +
|
| 210 | +Therefore, the quickest solution is to comment out the `TB_API_PASSWORD` environment variable in the `mc-infra-manager` service defined in the `./conf/docker/docker-compose.yaml` file if it is set, and then restart the service. |
| 211 | +
|
| 212 | +### Version Detection Issues |
| 213 | +If the version cannot be detected from docker compose ps, the command will fall back to reading the docker-compose.yaml file. Ensure that the docker-compose.yaml file contains the correct image version for mc-infra-manager. |
| 214 | +
|
| 215 | +### Permission Issues |
| 216 | +Make sure the user has proper permissions to: |
| 217 | +- Execute docker commands (user should be in docker group) |
| 218 | +- Create directories in `$HOME/go/src/github.com/cloud-barista/` |
| 219 | +- Execute git commands |
| 220 | +- Run bash scripts |
| 221 | +
|
| 222 | +### Prerequisites Missing |
| 223 | +If initialization fails due to missing prerequisites (such as `uv`), the error message will provide guidance. Install the required prerequisites and try again. |
0 commit comments