diff --git a/app-config.yaml b/app-config.yaml index f6f71478d0..c6857a3327 100644 --- a/app-config.yaml +++ b/app-config.yaml @@ -76,7 +76,7 @@ techdocs: generators: techdocs: 'docker' # Alternatives - 'local' publisher: - type: 'local' # Alternatives - 'googleGcs'. Read documentation for using alternatives. + type: 'local' # Alternatives - 'googleGcs' - 'awsS3'. Read documentation for using alternatives. sentry: organization: my-company diff --git a/docs/assets/techdocs/aws-s3.png b/docs/assets/techdocs/aws-s3.png new file mode 100644 index 0000000000..e0f3580c20 Binary files /dev/null and b/docs/assets/techdocs/aws-s3.png differ diff --git a/docs/features/techdocs/README.md b/docs/features/techdocs/README.md index 50cadc7b27..413db013b6 100644 --- a/docs/features/techdocs/README.md +++ b/docs/features/techdocs/README.md @@ -110,12 +110,12 @@ providers are used. | GitLab | Yes ✅ | | GitLab Enterprise | Yes ✅ | -| File Storage Provider | Support Status | Track status | -| --------------------------------- | -------------- | ----------------------------------------------------------- | -| Local Filesystem of Backstage app | Yes ✅ | | -| Google Cloud Storage (GCS) | Yes ✅ | | -| Amazon Web Services (AWS) S3 | No ❌ | [#3714](https://github.com/backstage/backstage/issues/3714) | -| Azure Storage | No ❌ | | +| File Storage Provider | Support Status | +| --------------------------------- | -------------- | +| Local Filesystem of Backstage app | Yes ✅ | +| Google Cloud Storage (GCS) | Yes ✅ | +| Amazon Web Services (AWS) S3 | Yes ✅ | +| Azure Storage | No ❌ | [Reach out to us](#feedback) if you want to request more platforms. diff --git a/docs/features/techdocs/configuration.md b/docs/features/techdocs/configuration.md index b3cb349778..7ab04c5a81 100644 --- a/docs/features/techdocs/configuration.md +++ b/docs/features/techdocs/configuration.md @@ -52,7 +52,7 @@ techdocs: # techdocs.publisher.type can be - 'local' or 'googleGcs' (awsS3, azureStorage, etc. to be available as well). # When set to 'local', techdocs-backend will create a 'static' directory at its root to store generated documentation files. - # When set to 'googleGcs', techdocs-backend will use a Google Cloud Storage Bucket to store generated documentation files. + # When set to 'googleGcs' or 'awsS3', techdocs-backend will use a Google Cloud Storage Bucket to store generated documentation files. type: 'local' @@ -70,4 +70,14 @@ techdocs: # Cloud Storage Bucket Name bucketName: 'techdocs-storage', + # Required when techdocs.publisher.type is set to 'awsS3'. Skip otherwise. + + awsS3: + # An API key is required to write to a storage bucket. + credentials: + $file: '/path/to/aws_application_credentials.json', + + # AWS S3 Bucket Name + bucketName: 'techdocs-storage', + ``` diff --git a/docs/features/techdocs/using-cloud-storage.md b/docs/features/techdocs/using-cloud-storage.md index c7b5ec9a9f..ba37f8d631 100644 --- a/docs/features/techdocs/using-cloud-storage.md +++ b/docs/features/techdocs/using-cloud-storage.md @@ -93,3 +93,166 @@ techdocs: Your Backstage app is now ready to use Google Cloud Storage for TechDocs, to store the static generated documentation files. + +## Configuring AWS S3 Bucket with TechDocs + +Follow the +[official AWS S3 documentation](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html) +for the latest instructions on the following steps involving AWS S3. + +**1. Set `techdocs.publisher.type` config in your `app-config.yaml`** + +Set `techdocs.publisher.type` to `'awsS3'`. + +```yaml +techdocs: + publisher: + type: 'awsS3' +``` + +**2. AWS Policies** + +AWS Policies lets you **control access** to Amazon Web Services (AWS) products and ressources. +Here we will use a user policy **and** a bucket policy to show you the different possibilities you have but you can use only one. + +AWS S3 + +This is an example of how you can manage your poilicies: + +a. Admin user creates a **bucket policy** granting a set of permissions to our TechDocs user. + +b. Admin user attaches a **user policy** to the TechDocs user granting additional permissions. + +c. TechDocs User then tries permissions granted via both the **bucket** policy and the **user** policy. + +**2.1 Creation** + +**2.1.1 Create an Admin user** (if you don't have one yet) + +Create an **administrator user** `ADMIN_USER` and grant him administrator privileges by attaching a user policy giving him **full access**. +Note down the Admin User credentials and IAM User Sign-In URL as you will need to use these informations in the next step. + +**2.1.2 Create an AWS S3 Bucket** + +Using the credentials of your Admin User `ADMIN_USER`, and the special IAM user sign-in URL, create a dedicated **bucket** for TechDocs sites. techdocs-backend will publish +documentation to this bucket. TechDocs will fetch files from here to serve +documentation in Backstage. + +Set the name of the bucket to `techdocs.publisher.awsS3.bucketName`. + +```yaml +techdocs: + publisher: + type: 'awsS3' + awsS3: + credentials: + $file: '/path/to/aws_application_credentials.json' + bucketName: 'name-of-techdocs-storage-bucket' +``` + +**2.1.3 Create the `TechDocs` user** + +This user will be used to interact with your bucket, it will only have permissions to **get - put** objects. + +In the IAM console, do the following: + +- Create a new user, `TechDocs` +- Note down the TechDocs User credentials +- Note down the Amazon Resource Name (ARN) for the TechDocs user. In the IAM console, select the TechDocs user, and you can find the user ARN in the Summary tab. + +**2.2 Attach policies** + +Remember that you can use Bucket policy **or** User policy. +Just make sure that you grant all the permissions to the TechDocs user: `3:PutObject`, `s3:GetObject`, `s3:ListBucket` and `s3:GetBucketLocation`. + +**2.2.1 Create the bucket policy** + +You now have to attach the following policity to your bucket in the Permission section: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "statement1", + "Effect": "Allow", + "Principal": { + "AWS": "arn:aws:iam::YOUR_ACCOUNT_ID:user/TechDocs" + }, + "Action": [ + "s3:GetBucketLocation", + "s3:ListBucket" + ], + "Resource": [ + "arn:aws:s3:::name-of-techdocs-storage-bucket" + ] + }, + { + "Sid": "statement2", + "Effect": "Allow", + "Principal": { + "AWS": "arn:aws:iam::YOUR_ACCOUNT_ID:user/TechDocs" + }, + "Action": [ + "s3:GetObject" + ], + "Resource": [ + "arn:aws:s3:::name-of-techdocs-storage-bucket/*" + ] + } + ] +} +``` + +- The first statement grants **TechDocs User** the bucket operation permissions `s3:GetBucketLocation` and `s3:ListBucket` which are permissions required by the console. +- The second statement grants the `s3:GetObject` permission. +(**NOTE :** if you do not use the user policy defined below you must also add the `s3:PutObject` permission to allow the TechDocs user to add objects.) + +**2.2.2 Create the user policy** + +Create an inline policy for the TechDocs user by using the following policy: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "PermissionForObjectOperations", + "Effect": "Allow", + "Action": [ + "s3:PutObject" + ], + "Resource": [ + "arn:aws:s3:::name-of-techdocs-storage-bucket/*" + ] + } + ] +} +``` + +See more details in the section [Working with Inline Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage.html). + +Now you need to create your credentials file (`.json`) with the `TechDocs` User credentials: + +```json +{ + "accessKeyId": "TECHDOCS_USER_ACCESS_KEY_ID", + "secretAccessKey": "TECHDOCS_USER_SECRET_ACCESS_KEY" +} +``` + +Make it available in your Backstage server and/or your local development server and set it in the app config techdocs.publisher.awsS3.credentials. + +```yaml +techdocs: + publisher: + type: 'awsS3' + awsS3: + credentials: + $file: '/path/to/aws_application_credentials.json' +``` + +**3. That's it!** + +Your Backstage app is now ready to use AWS S3 for TechDocs, to +store the static generated documentation files.