AWSMP Guides

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 [[email protected]](mailto:[email protected])
+
+### Support
+In case of any issues please contact [[email protected]](mailto:[email protected])

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: `[email protected] [email protected]`.
+  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 [[email protected]](mailto:[email protected]) please.
+
+
+### Support
+In case of any issues please contact [[email protected]](mailto:[email protected]).

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 [[email protected]](mailto:[email protected])