feat(techdocs): update docs
This commit is contained in:
Remi
+1
-1
@@ -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
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 298 KiB |
@@ -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.
|
||||
|
||||
|
||||
@@ -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',
|
||||
|
||||
```
|
||||
|
||||
@@ -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.
|
||||
|
||||
<img data-zoomable src="../../assets/techdocs/aws-s3.png" alt="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.
|
||||
|
||||
Reference in New Issue
Block a user