diff --git a/docs/awsmp/access.md b/docs/awsmp/access.md new file mode 100644 index 0000000..58785a6 --- /dev/null +++ b/docs/awsmp/access.md @@ -0,0 +1,36 @@ +# Access Guide + +> This software product is delivered without TLS (Transport Layer Security) configured by default. +> If access from the public internet is required, it is strongly recommended to follow the best practices of configuring HTTPS access. + +As soon as the AWS CloudFormation stack of EPAM Syndicate Rightsizer changed +its state to `CREATE_COMPLETE` you can access the product in the following ways: + +### CLI +To access the EPAM Syndicate Rightsizer's CLI please follow these steps: +1. Verify if the inbound/outbound SSH traffic is allowed to port 22 by the +Security Group that is applied to the product instance; +2. Make sure that you have the SSH key used while instance provisioning; +3. Ensure the key file has read-only permission for the owner or file user. +If not, set such permission with the command: `chmod 400 $SSH_KEY_NAME` where +`$SSH_KEY_NAME` is replaced with the actual ssh key file name. +4. Connect to the product instance using the SSH key using this command: +`ssh -i $SSH_KEY_NAME admin@$INSTANCE_PUBLIC_DNS` where: + - `$SSH_KEY_NAME` is the actual name of the key file; + - `$INSTANCE_PUBLIC_DNS` is the actual public DNS of the instance. +5. After you successfully log in check if the syndicate CLI is available with the +command `syndicate --version`. + +### Defect Dojo +To access the Defect Dojo Web Interface do the following steps: +1. Verify if the inbound/outbound HTTP traffic is allowed to 80 port by the +Security Group that is applied to the product instance; +2. Open https://INSTANCE-PUBLIC-DNS:80 (replace INSTANCE-PUBLIC-DNS with the actual value) +in your browser; the Defect Dojo web app will open. + +### API +Coming Soon. +In case of urgent need please contact [SupportSyndicateTeam@epam.com](mailto:SupportSyndicateTeam@epam.com) + +### Support +In case of any issues please contact [SupportSyndicateTeam@epam.com](mailto:SupportSyndicateTeam@epam.com) \ No newline at end of file diff --git a/docs/awsmp/provisioning-via-AWS-CloudFormation.md b/docs/awsmp/provisioning-via-AWS-CloudFormation.md new file mode 100644 index 0000000..008291f --- /dev/null +++ b/docs/awsmp/provisioning-via-AWS-CloudFormation.md @@ -0,0 +1,87 @@ +# EPAM Syndicate Rightsizer provisioning via AWS CloudFormation + +AWS CloudFormation is a recommended way to provision EPAM Syndicate Rightsizer instance. +It provides ability to specify start parameters for the instance and make it clear and easy to get the configuration outcome. + +Please follow these steps to get the ready-to-use product. + +## 1. AWS Marketplace Subscription +Subscribe to EPAM Syndicate Rightsizer in AWS Marketplace. Once done you will be redirected to AWS CloudFormation Console +where the following list of parameters should be specified. + +## 2. Specify AWS CloudFormation stack parameters + +Required parameters: +- **AWS Subnet id:** сhoose a subnet to launch the instance in; +- **AWS Security groups ids:** specify security groups to be attached to the instance. By default, +the following ports are used: 80 (Defect dojo), 8085 (API), 9000 (Minio API). +Consider to select Security Group with the ports opened if these services should be available outside the instance; +- **EC2 Instance Type:** choose a type for the instance; +- **SSH Key pair name:** choose key pair. Make sure you have access to the selected key. + +Optional parameters: +- **Instance Name:** name for the instance. Stack name will be used as instance name if custom value is not specified; +- **IAM Role Name:** name of AWS IAM Role to be attached to the instance. The role is used by EPAM Syndicate Rightsizer to access accounts resources. + Keep the field empty if you do not want any role to be attached; +- **Tenant Name:** name for the tenant to be activated during service configuration. The + tenant represents the AWS Account where the instance is launched. The name can contain ONLY uppercase letters, digits, dashes and underscores. + If the value is not specified, the default `TENANT_1` will be used; +- **Admin Emails:** list of emails of administrators split by a space. Example: `admin1@yourcorp.com admin2@yourcorp.com`. + Keep the field empty to not configure any emails. + +Click `Next` if all parameters are set. + +## 3. Configure stack options + +Configure AWS CloudFormation options provided by AWS: + +- **Permissions:** specify IAM Role that will be used by AWS CloudFormation to deploy the stack. The role must have + permissions to create such AWS resources: EC2 Launch Templates, EC2 Instance Profiles, EC2 Instances. + Credentials of the user who deploys the stack are used in case of no Role is specified; +- **Stack failure options:** choose the `Preserve successfully provisioned resources` option. It will ensure that You will + still be able to access the instance in case the initial setup fails. If such event happens You will be able to access + initialization logs and share them with EPAM Syndicate Team. If You choose the default value for this option, + AWS CloudFormation will terminate the instance immediately when the installation fails; +- **Capabilities:** confirm that You `Acknowledge that AWS CloudFormation might create IAM resources.`. It's required + if You specified IAM Role in the previous section. No custom role will be created but the one You have specified will + be attached to the instance profile. + +Click `Next` if all options are set. + +## 4. Create stack + +Review all the parameters and options and click `Submit`. + +## 5. After the AWS CloudFormation stack creation + +The stack will create such resources: +- EC2 Launch Template +- EC2 Instance Profile +- EC2 Instance + +The stack will be in `CREATE_IN_PROGRESS` status for as long as it takes the EPAM Syndicate Rightsizer instance be created and initially configured. +Usually it takes up to 10 minutes. + +### In case of success +The `CREATE_COMPLETE` status indicates the creation, configuration and healthcheck are successfully finished and the EPAM Syndicate Rightsizer is ready to be used. +To begin the EPAM Syndicate Rightsizer usage please follow the steps described in the access guide. + +### In case of issues +If something goes wrong during the setup, the AWS CloudFormation stack will change its status to `CREATE_FAILED`. +In case the `Preserve successfully provisioned resources` option was enabled on parameters section it is possible to provide instance initialization log to the EPAM Syndicate Team. + +Please follow these steps to download the initialization log file and share it with the support team: +1. Make sure the instance's port 22 is open for your IP address; +2. Make sure there is access to the Key Pair file used on instance startup; +3. Execute the following command to get the log file from the instance: + +`scp -i $SSH_KEY_NAME admin@$INSTANCE_PUBLIC_DNS:/var/log/r8s-init.log /$YOUR_LOCAL_DIRECTORY/`, where: + - `$SSH_KEY_NAME` is the actual name of the key file; + - `$INSTANCE_PUBLIC_DNS` is the actual public DNS of the instance; + - `$YOUR_LOCAL_DIRECTORY` is the path on you local machine where the log file will be saved. +4. After downloading the file the AWS CloudFormation stack can be deleted; +5. Attach the log to the email and send it to [SupportSyndicateTeam@epam.com](mailto:SupportSyndicateTeam@epam.com) please. + + +### Support +In case of any issues please contact [SupportSyndicateTeam@epam.com](mailto:SupportSyndicateTeam@epam.com). diff --git a/docs/awsmp/upgrade.md b/docs/awsmp/upgrade.md new file mode 100644 index 0000000..f9650cc --- /dev/null +++ b/docs/awsmp/upgrade.md @@ -0,0 +1,66 @@ +# Update Guide + +The flow of product update is fully automated. + +EPAM Syndicate Rightsizer implements the incremental upgrades flow - it's only +possible to update software through each successive version without skipping any intermediate versions. + +Please follow the following step to update the product: + +### 1. Connect to instance via SSH: +Connect to the product instance using the SSH key using this command: +`ssh -i $SSH_KEY_NAME admin@$INSTANCE_PUBLIC_DNS` where: + - `$SSH_KEY_NAME` is the actual name of the key file; + - `$INSTANCE_PUBLIC_DNS` is the actual public DNS of the instance. + +### 2. List releases +Once log in to instance, please execute the following command in order to list all the releases available starting from the current version: + +`r8s-init list` + +Here is the command output sample: + +| Version | Release Date | URL | Prerelease | Draft | +|---------|----------------------|---------------------------------------------------------------------------------------------------------------------|------------|-------| +| 3.12.0 | NEW RELEASE DATE | [NEW RELEASE LINK](https://github.com/epam/syndicate-rule-engine/releases/tag/5.5.0) | false | false | +| 3.11.0* | 2024-01-01T09:01:13Z | [https://github.com/epam/r8s/releases/tag/3.11.0](https://github.com/epam/syndicate-rule-engine/releases/tag/5.5.0) | false | false | + +The installed version is marked with asteriks `*` nearby the version number: `3.11.0*`. + +This command is integrated with [GitHub releases of the product](https://github.com/epam/r8s/releases). + +### 3. Check if update available +To check if new release is available please execute the following command: + +`r8s-init update --check` + +The command will return the `Up-to-date` response with the `0` status code if update is not available and `1` status code +otherwise - this may be useful for any automation build atop of `r8s-init` tool. + +### 4. Syndicate Rightsizer Update +To initiate the update to the next version please execute the following command: + +`r8s-init update --yes` + +**Note:** no prompt will be shown if you specify `--yes` flag. + +The command produces logs to console notifying the user about the update progress. +> The command is fail-safe. The 'r8s-init' tool will rollback all the changes made to the software in case of failure. +> +> This allows to return the product to the previous state. + +In case update successfully ended - the following message will be diplayed: `Done`; + +### 5. Defect Dojo Update + +To update Defect Dojo use: + +```bash +r8s-init update --defectdojo +``` + +> This update is fail-safe as well. + + +### Support +In case of any issues please contact [SupportSyndicateTeam@epam.com](mailto:SupportSyndicateTeam@epam.com) \ No newline at end of file