Google Cloud Storage working with TechDocs (publish and fetch)
Plus 1. Introduce ncessary configs to connect with storage 2. Introduce config to prefer CI build of docs, or techdocs-backend to build and publish them. 3. Write guide how to use Google Cloud Storage with TechDocs 4. Add a TechDocs Configuration reference page in docucmentation
This commit is contained in:
Himanshu Mishra
@@ -0,0 +1,71 @@
|
||||
---
|
||||
id: configuration
|
||||
title: TechDocs Configuration Options
|
||||
description: Reference documentation for configuring TechDocs using app-config.yaml
|
||||
---
|
||||
|
||||
Using the `app-config.yaml` in the Backstage app, you can configure TechDocs using several options.
|
||||
This page serves as a reference to all the available configuration options for TechDocs.
|
||||
|
||||
|
||||
```yaml
|
||||
# File: app-config.yaml
|
||||
|
||||
techdocs:
|
||||
|
||||
# TechDocs makes API calls to techdocs-backend using this URL. e.g. get docs of an entity, get metadata, etc.
|
||||
|
||||
requestUrl: http://localhost:7000/api/techdocs
|
||||
|
||||
|
||||
# Just another route in techdocs-backend where TechDocs requests the static files from. This URL uses an HTTP middleware
|
||||
# to serve files from either a local directory or an External storage provider.
|
||||
|
||||
storageUrl: http://localhost:7000/api/techdocs/static/docs
|
||||
|
||||
|
||||
# generators.techdocs can have two values: 'docker' or 'local'. This is to determine how to run the generator - whether to
|
||||
# spin up the techdocs-container docker image or to run mkdocs locally (assuming all the dependencies are taken care of).
|
||||
# You want to change this to 'local' if you are running Backstage using your own customer Docker setup and want to avoid running
|
||||
# into Docker in Docker situation. Read more here
|
||||
# https://backstage.io/docs/features/techdocs/getting-started#disable-docker-in-docker-situation-optional
|
||||
|
||||
generators:
|
||||
techdocs: 'docker'
|
||||
|
||||
|
||||
# techdocs.builder can be either 'local' or 'ci.
|
||||
# If builder is set to 'local' and you open a TechDocs page, techdocs-backend will try to build the docs, publish to storage
|
||||
# and show the generated docs afterwords. This is the "Basic" setup of the TechDocs Architecture.
|
||||
# If builder is set to 'ci', techdocs-backend will only fetch the docs and will NOT try to build and publish. In this case of 'ci',
|
||||
# we assume that docs are being built in the CI/CD pipeline of the repository. This is the "Recommended" setup of the architecture.
|
||||
# Read more here https://backstage.io/docs/features/techdocs/architecture
|
||||
|
||||
builder: 'local'
|
||||
|
||||
|
||||
# techdocs.publisher is used to configure the Storage option, whether you want to use the local filesystem to store generated docs
|
||||
# or you want to use External storage providers like Google Cloud Storage, AWS S3, etc.
|
||||
|
||||
publisher:
|
||||
|
||||
# techdocs.publisher.type can be - 'local' or 'google_gcs' (aws_s3, azure_storage, 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 'google_gcs', techdocs-backend will use a Google Cloud Storage Bucket to store generated documentation files.
|
||||
|
||||
type: 'local'
|
||||
|
||||
|
||||
# Required when techdocs.publisher.type is set to 'google_gcs'. Skip otherwise.
|
||||
|
||||
google:
|
||||
# An API key is required to write to a storage bucket.
|
||||
pathToKey: '/path/to/google_application_credentials.json',
|
||||
|
||||
# Your GCP Project ID where the Cloud Storage Bucket is hosted.
|
||||
projectId: 'gcp-project-id'
|
||||
|
||||
# Cloud Storage Bucket Name
|
||||
bucketName: 'techdocs-storage',
|
||||
|
||||
```
|
||||
@@ -0,0 +1,80 @@
|
||||
---
|
||||
id: using-cloud-storage
|
||||
title: Using Cloud Storage for TechDocs generated files
|
||||
description: Using Cloud Storage for TechDocs generated files
|
||||
---
|
||||
|
||||
In the [TechDocs architecture](./architecture.md) you have the option to choose where you want to store
|
||||
the Generated static files which TechDocs uses to render documentation. In both the "Basic" and "Recommended"
|
||||
setup, you can add cloud storage providers like Google GCS, Amazon AWS S3, etc. By default, TechDocs
|
||||
uses the local filesystem of the `techdocs-backend` plugin in the "Basic" setup. And in the recommended setup,
|
||||
having one of the cloud storage is a prerequisite. Read more on the TechDocs Architecture documentation page.
|
||||
|
||||
On this page you you can read how to enable them.
|
||||
|
||||
## Configuring Google GCS Bucket with TechDocs
|
||||
|
||||
Follow the [official Google Cloud documentation](https://googleapis.dev/nodejs/storage/latest/index.html#quickstart) for the latest instructions
|
||||
on the following steps involving GCP.
|
||||
|
||||
**1. Set `techdocs.publisher.type` config in your `app-config.yaml`**
|
||||
|
||||
Set `techdocs.publisher.type` to `'google_gcs'`.
|
||||
|
||||
```yaml
|
||||
techdocs:
|
||||
publisher:
|
||||
type: 'google_gcs'
|
||||
```
|
||||
|
||||
**2. GCP (Google Cloud Platform) Project**
|
||||
|
||||
Create or choose a dedicated GCP project. Set `techdocs.publisher.google.projectId` to the project ID.
|
||||
|
||||
```yaml
|
||||
techdocs:
|
||||
publisher:
|
||||
type: 'google_gcs'
|
||||
google:
|
||||
projectId: 'gcp-project-id
|
||||
```
|
||||
|
||||
**3. Service account API key**
|
||||
|
||||
Create a new Service Account and a key associated with it. In roles of the service account, use "Storage Admin".
|
||||
|
||||
If you want to create a custom role, make sure to include both `get` and `create` permissions for both "Objects" and "Buckets". See https://cloud.google.com/storage/docs/access-control/iam-permissions
|
||||
|
||||
A service account can have many keys. Open your newly created account's page (in IAM & Admin console), and create a new key. Use JSON format for the key.
|
||||
|
||||
A `<GCP-PROJECT-ID-random-uid>.json` file will be downloaded. This is the secret key TechDocs will use to make API calls. Make it available in your Backstage server and/or your local development server and set it in the app config `techdocs.publisher.google.pathToKey`.
|
||||
|
||||
```yaml
|
||||
techdocs:
|
||||
publisher:
|
||||
type: 'google_gcs'
|
||||
google:
|
||||
projectId: 'gcp-project-id'
|
||||
pathToKey: '/path/to/google_application_credentials.json'
|
||||
```
|
||||
|
||||
**4. GCS Bucket**
|
||||
|
||||
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
|
||||
|
||||
```yaml
|
||||
techdocs:
|
||||
publisher:
|
||||
type: 'google_gcs'
|
||||
google:
|
||||
projectId: 'gcp-project-id'
|
||||
pathToKey: '/path/to/google_application_credentials.json'
|
||||
bucketName: 'name-of-techdocs-storage-bucket'
|
||||
```
|
||||
|
||||
**5. That's it!**
|
||||
|
||||
Your Backstage app is now ready to use Google Cloud Storage for TechDocs, to store the static generated documentation files.
|
||||
Reference in New Issue
Block a user