|
| 1 | +--- |
| 2 | +title: Install Mod via CLI |
| 3 | +sidebar_label: Install Mod via CLI |
| 4 | +--- |
| 5 | + |
| 6 | +# Install a Mod using Guardrails CLI |
| 7 | + |
| 8 | +In this guide, you will: |
| 9 | +- Install a mod in a Guardrails workspace using the CLI. |
| 10 | +- Validate successful installation using the Guardrails UI. |
| 11 | + |
| 12 | +Guardrails supports installing [Mods](/guardrails/docs/reference/glossary#mod) via [Guardrails CLI](https://turbot.com/guardrails/docs/reference/cli) for various scenarios where command-line installation is preferred or required, including Government Cloud environments (e.g., AWS GovCloud) where UI-based interactions may be limited, automated deployment workflows and CI/CD pipelines, scripted installation processes for consistent deployments or restricted environments where direct web access is limited, and bulk mod installations across multiple workspaces. |
| 13 | + |
| 14 | +> [!IMPORTANT] |
| 15 | +> This CLI-based approach is particularly important for AWS GovCloud environments, where direct access to Turbot's mod registry is restricted because the registry is hosted in commercial AWS accounts. |
| 16 | +
|
| 17 | +## Prerequisites |
| 18 | + |
| 19 | +- [Turbot CLI installed and configured](https://turbot.com/guardrails/docs/reference/cli/installation) with appropriate credentials |
| 20 | +- Valid **Turbot/Owner** permissions in the target Guardrails [workspace](https://turbot.com/guardrails/docs/reference/glossary#workspace) |
| 21 | +- **Mod registry access**: Registration at [guardrails.turbot.com](https://guardrails.turbot.com) with approved mod download permissions |
| 22 | +- Network access to download mods from **guardrails.turbot.com** |
| 23 | +- One of the following access methods: |
| 24 | + - Access to a bastion host in your GovCloud environment, or |
| 25 | + - Direct network access from your local environment to the hosted workspace |
| 26 | + |
| 27 | +> [!NOTE] |
| 28 | +> **Mod Download Permissions**: Even with a guardrails.turbot.com account, you may not have permissions to download mods. If you encounter permission errors during mod download, contact [Turbot Support](https://support.turbot.com) to request access to allow to download mods. |
| 29 | +
|
| 30 | +## Step 1: Access Your Environment |
| 31 | + |
| 32 | +> [!NOTE] |
| 33 | +> If a bastion host is not available in your environment, you can create one using this guide: [Turbot Bastion Host](https://github.com/turbot/guardrails-samples/tree/main/enterprise_installation/turbot_bastion_host#turbot-bastion-host) |
| 34 | +
|
| 35 | +### For GovCloud Environments |
| 36 | + |
| 37 | +Log into the AWS account associated with your GovCloud production environment and connect to the main bastion host. |
| 38 | + |
| 39 | + |
| 40 | + |
| 41 | +### For Commercial Cloud Environments |
| 42 | + |
| 43 | +Ensure you have CLI access to your target environment with the [Turbot CLI](/guardrails/docs/reference/cli) properly configured. |
| 44 | + |
| 45 | + |
| 46 | + |
| 47 | +## Step 2: Download Mod |
| 48 | + |
| 49 | +Navigate to your desired directory for downloading the mod package, for example: `cd /turbot/mods` |
| 50 | + |
| 51 | +Download the desired mod package using this Guardrails CLI command. This fetches the specified mod from the Guardrails registry, e.g., @turbot/aws-iam. |
| 52 | + |
| 53 | +``` |
| 54 | +turbot download @turbot/aws-iam |
| 55 | +``` |
| 56 | + |
| 57 | + |
| 58 | + |
| 59 | +## Step 3: Install Mod to Workspace |
| 60 | + |
| 61 | +Upload and install the downloaded mod into your target workspace by executing the command below with the appropriate CLI profile. |
| 62 | + |
| 63 | +``` |
| 64 | +turbot up --zip-file turbot_aws-iam --profile <profile-name> |
| 65 | +``` |
| 66 | + |
| 67 | + |
| 68 | + |
| 69 | +## Step 4: Review |
| 70 | + |
| 71 | +- [ ] Verify successful installation by checking the Guardrails UI after approximately 20 minutes. Ensure the mod appears under **Admin > Mods**, the version matches the one uploaded (e.g., 5.43.x), and the mod status displays a green checkmark. |
| 72 | + |
| 73 | + |
| 74 | + |
| 75 | +## Next Steps |
| 76 | + |
| 77 | +Please see the following resources to learn more about Turbot Guardrails Enterprise: |
| 78 | + |
| 79 | +- Learn more about [Turbot Guardrails Enterprise - Architecture](/guardrails/docs/enterprise/architecture). |
| 80 | +- Learn about [Updating Mod](/guardrails/docs/enterprise/updating-stacks/mod-update). |
| 81 | + |
| 82 | +## Troubleshooting |
| 83 | + |
| 84 | +| Issue | Description | Guide | |
| 85 | +|----------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------| |
| 86 | +| Login Authentication Error | If you receive `Failed to login to guardrails mod registry: Incorrect username or password` error, verify your credentials by logging into [guardrails.turbot.com](https://guardrails.turbot.com/). If you've forgotten your password, use the password reset option. | | |
| 87 | +| Mod Download Permissions | If you receive `Failed to download mod: You do not have the necessary permissions to download @turbot/<mod-name> from guardrails.turbot.com` error, you need to request mod access through Turbot Support. | [Open Support Ticket](https://support.turbot.com) | |
| 88 | +| Mod Dependency | If the mod installation fails due the dependent/parent mod not installed. | [Troubleshoot Mod Peer Dependency Error](/guardrails/docs/guides/hosting-guardrails/troubleshooting/peer-mod-dependency-error#peer-mod-dependency-error) | |
| 89 | +| Further Assistance | If you continue to encounter issues, please open a ticket with us and attach the relevant information to assist you more efficiently. | [Open Support Ticket](https://support.turbot.com) | |
0 commit comments