TechDocs 생성 파일용 클라우드 스토리지 사용하기

원문 보기 위키 갱신 2026.10.07

TechDocs 아키텍처에서는 TechDocs가 문서 렌더링에 사용하는 생성된 정적 파일을 어디에 저장할지 선택할 수 있어요. "Basic"과 "Recommended" 설정 모두에서 Google GCS, Amazon AWS S3 등의 클라우드 스토리지 제공자를 추가할 수 있어요. 기본적으로 TechDocs는 "Basic" 설정에서 techdocs-backend 플러그인의 로컬 파일시스템을 사용해요. 그리고 권장 설정에서는 클라우드 스토리지 중 하나를 갖추는 것이 전제 조건이에요. 자세한 내용은 TechDocs 아키텍처 문서 페이지에서 읽어 보세요.

출처: 문서

본문

이 페이지에서 이를 활성화하는 방법을 읽을 수 있어요.

TechDocs로 Google GCS 버킷 구성하기

GCP가 포함된 다음 단계에 대한 최신 지침은 공식 Google Cloud 문서를 따르세요.

app-config.yaml에서 techdocs.publisher.type 구성을 설정

techdocs.publisher.type을 'googleGcs'로 설정하세요.

techdocs:  publisher:    type: 'googleGcs'

GCS 버킷 만들기

TechDocs 사이트용 전용 Google Cloud Storage 버킷을 만드세요. techdocs-backend가 이 버킷에 문서를 게시해요. TechDocs는 여기에서 파일을 가져와 Backstage에서 문서를 서빙해요. 버킷 이름은 전 세계적으로 고유하다는 점에 유의하세요.

app-config.yaml에서 techdocs.publisher.googleGcs.bucketName 구성을 방금 만든 버킷 이름으로 설정하세요. techdocs.publisher.googleGcs.projectId를 버킷이 들어 있는 Google Cloud 프로젝트의 ID로 설정하세요.

techdocs:  publisher:    type: 'googleGcs'    googleGcs:      bucketName: 'name-of-techdocs-storage-bucket'      projectId: 'name-of-project'

3a. (권장) 환경 변수를 사용한 인증

GCS Node.js 클라이언트는 자동으로 GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 사용해 Google Cloud에 인증해요. Compute Engine, Google Kubernetes Engine 등에서는 이미 설정되어 있을 수 있어요. 자세한 내용은 https://cloud.google.com/docs/authentication/production 을 읽으세요.

3b. app-config.yaml을 사용한 인증

(3a)를 선호하지 않고 선택적으로 서비스 계정을 사용하고 싶다면 다음 단계를 따를 수 있어요.

새 서비스 계정과 그와 연결된 키를 만드세요. 서비스 계정의 역할에서는 "Storage Object Admin"을 사용하세요.

커스텀 역할을 만들고 싶다면 "Objects"와 "Buckets" 모두에 get과 create 권한을 모두 포함해야 해요. https://cloud.google.com/storage/docs/access-control/iam-permissions 참고

서비스 계정은 여러 키를 가질 수 있어요. 새로 만든 계정의 페이지(IAM & Admin 콘솔)를 열고 새 키를 만드세요. 키 형식은 JSON을 사용하세요.

<GCP-PROJECT-ID-random-uid>.json 파일이 다운로드돼요. 이것이 TechDocs가 API 호출에 사용할 비밀 키예요. 이를 Backstage 서버 및/또는 로컬 개발 서버에서 사용할 수 있게 하고 앱 구성 techdocs.publisher.googleGcs.credentials에 설정하세요.

techdocs:  publisher:    type: 'googleGcs'    googleGcs:      bucketName: 'name-of-techdocs-storage-bucket'      credentials:        $file: '/path/to/google_application_credentials.json'

참고: 서버에서 google_application_credentials.json 파일을 사용할 수 있게 하기 어렵다면, 파일의 내용을 환경 변수로 설정해 사용할 수 있어요. 그런 다음 다음을 사용하세요.

techdocs:  publisher:    type: 'googleGcs'    googleGcs:      bucketName: 'name-of-techdocs-storage-bucket'      credentials: ${GOOGLE_APPLICATION_CREDENTIALS}

사용 중인 서비스 계정이 버킷과 같은 프로젝트에서 생성된 것이라면 projectId 필드를 설정할 필요가 없어요. 그렇지 않다면 기본 자격 증명처럼 재정의해야 해요.

techdocs:  publisher:    type: 'googleGcs'    googleGcs:      bucketName: 'name-of-techdocs-storage-bucket'      credentials: ${GOOGLE_APPLICATION_CREDENTIALS}      projectId: 'name-of-project'

이게 전부예요!

이제 Backstage 앱이 TechDocs용 Google Cloud Storage를 사용해 정적으로 생성된 문서 파일을 저장하고 읽을 준비가 됐어요.

기본 스토리지 구성 확장하기

Google Cloud Storage 클라이언트의 비표준 구성이 필요하다면 TechdocsPublisherExtensionPoint를 살펴봐야 해요. 클라이언트를 구성하는 데 사용될 커스텀 StorageOptions를 등록할 수 있어요. 이렇게 하려면 모듈 init 안에서 게시자 설정을 등록해야 해요. 예시는 다음과 같아요.

export const gcsPublisherCustomizer = createBackendModule({  pluginId: 'techdocs',  moduleId: 'gcs-publisher-customizer',  register(reg) {    reg.registerInit({      deps: {        techdocsExtensionPoint: techdocsPublisherExtensionPoint,      },      async init({ techdocsExtensionPoint }) {        const customOptions: StorageOptions = {          userAgent: 'my-custom-user-agent',        };        techdocsExtensionPoint.registerPublisherSettings(          'googleGcs',          customOptions,        );      },    });  },});

TechDocs로 AWS S3 버킷 구성하기

app-config.yaml에서 techdocs.publisher.type 구성을 설정

techdocs.publisher.type을 'awsS3'로 설정하세요.

techdocs:  publisher:    type: 'awsS3'

S3 버킷 만들기

TechDocs 사이트 저장용 전용 AWS S3 버킷을 만드세요. 공식 문서를 참고하세요. Terraform 예시.

TechDocs는 이 버킷에 문서를 게시하고 여기에서 파일을 가져와 Backstage에서 문서를 서빙해요. 버킷 이름은 전 세계적으로 고유하다는 점에 유의하세요.

app-config.yaml에서 버킷 이름과 리전을 방금 만든 버킷의 이름으로 설정하세요.

techdocs:  publisher:    type: 'awsS3'    awsS3:      bucketName: 'name-of-techdocs-storage-bucket'      region: 'us-east-1'

TechDocs를 관리할 최소 AWS IAM 정책 만들기

TechDocs를 S3 버킷에 쓰려면 IAM 정책이 최소한 다음 권한을 가져야 해요.

버킷 메타데이터를 가져오는 s3:ListBucket
버킷에 파일을 업로드하는 s3:PutObject
다시 게시하는 동안 오래된 콘텐츠를 삭제하는 s3:DeleteObject와 s3:DeleteObjectVersion

S3 버킷에서 TechDocs를 읽으려면 IAM 정책이 최소한 다음 권한을 가져야 해요.

s3:ListBucket - 버킷 메타데이터를 가져오려면
s3:GetObject - 버킷에서 파일을 가져오려면

참고

대소문자를 구분하는 엔터티 메타데이터가 포함된 이전 스타일의 경로 형식에서 문서 객체를 마이그레이션해야 한다면, 마이그레이션을 수행하기 위한 추가 권한을 추가해야 해요. 다음을 포함해요.

s3:PutObjectAcl(파일 복사용, 자세한 내용은 여기)
s3:DeleteObject와 s3:DeleteObjectVersion(마이그레이션된 파일 삭제용, 자세한 내용은 여기)

...그리고 권한이 버킷 자체와 버킷 아래의 모든 리소스에 적용되는지 확인해야 해요. 아래 예시 정책을 참고하세요.

{  "Version": "2012-10-17",  "Statement": [    {      "Sid": "TechDocsWithMigration",      "Effect": "Allow",      "Action": [        "s3:PutObject",        "s3:GetObject",        "s3:DeleteObjectVersion",        "s3:ListBucket",        "s3:DeleteObject",        "s3:PutObjectAcl"      ],      "Resource": ["arn:aws:s3:::your-bucket", "arn:aws:s3:::your-bucket/*"]    }  ]}

4a. (권장) 환경 변수를 사용해 AWS 방식으로 인증 설정

인증에 대해서는 AWS 보안 모범 사례 가이드를 따라야 해요.

TechDocs는 S3 버킷의 파일과 메타데이터를 읽을 수 있는 접근 권한이 필요해요. 사용자용 정책을 만드는 경우 ListBucket, GetObject, PutObject에 대한 접근 권한이 부여되는지 확인해야 해요.

환경 변수

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_REGION

가 설정되어 있고 2단계에서 만든 버킷에 접근하는 데 사용할 수 있다면, AWS SDK V3 Node.js 클라이언트가 인증에 이를 사용해요. Node.js에서 환경 변수로 자격 증명을 로드하는 방법은 공식 문서를 참고하세요.

환경 변수가 없으면 AWS SDK는 자격 증명을 위해 ~/.aws/credentials 파일을 읽으려고 해요. 공식 문서를 참고하세요.

Backstage를 Amazon EC2, Amazon ECS 또는 Amazon EKS에 배포한다면 접근 키를 별도로 얻을 필요가 없어요. 버킷에 접근 권한이 있는 적절한 IAM 역할을 정의하면 환경에 자동으로 제공될 수 있어요. IAM 역할 사용에 대한 자세한 내용은 공식 AWS 문서에서 읽어 보세요.

4b. aws.accounts를 통해 app-config.yaml을 사용한 인증

AWS 자격 증명과 리전은 app-config.yaml을 통해 AWS SDK에 제공될 수 있어요. 아래 구성을 사용할 수 있다면 기존 AWS_* 환경 변수와 ~/.aws/credentials 구성 파일보다 이것이 사용돼요.

techdocs:  publisher:    type: 'awsS3'    awsS3:      bucketName: 'name-of-techdocs-storage-bucket'      accountId: '123456789012'      region: ${AWS_REGION}aws:  accounts:    - accountId: '123456789012'      accessKeyId: ${AWS_ACCESS_KEY_ID}      secretAccessKey: ${AWS_SECRET_ACCESS_KEY}

자격 증명을 얻는 방법은 공식 AWS 문서를 참고하세요.

4c. integrations.awsS3를 통해 app-config.yaml을 사용한 인증

이미 AWS S3 통합이 있다면 이를 사용해 AWS S3에 인증할 수 있어요.

techdocs:  publisher:    type: 'awsS3'    awsS3:      bucketName: 'name-of-techdocs-storage-bucket'      region: 'eu-west-1'integrations:  awsS3:    - accessKeyId: ${AWS_ACCESS_KEY_ID}      secretAccessKey: ${AWS_SECRET_ACCESS_KEY}

이렇게 하면 통합의 자격 증명을 사용해 AWS S3에 인증하며 app-config.yaml에 추가 구성이 필요하지 않아요. 하지만 S3 통합이 여러 개라면, techdocs.publisher.awsS3.credentials 구성에 accessKeyId를 설정해 대상 통합을 지정해야 해요.

techdocs:  publisher:    type: 'awsS3'    awsS3:      bucketName: 'name-of-techdocs-storage-bucket'      region: 'eu-west-1'      credentials:        accessKeyId: ${AWS_ACCESS_KEY_ID_1}integrations:  awsS3:    - accessKeyId: ${AWS_ACCESS_KEY_ID_1}      secretAccessKey: ${AWS_SECRET_ACCESS_KEY_1}    - accessKeyId: ${AWS_ACCESS_KEY_ID_2}      secretAccessKey: ${AWS_SECRET_ACCESS_KEY_2}

4d. 가정 역할(assumed role)을 사용한 인증 여러 AWS 계정을 가진 사용자는 다른 AWS 계정에 있는 S3 스토리지용 역할을 사용하고 싶을 수 있어요. 아래처럼 roleArn 매개변수를 사용하면 S3에 접근하기 전에 역할을 가정하도록 TechDocs 게시자에게 지시할 수 있어요.

techdocs:  publisher:    type: 'awsS3'    awsS3:      bucketName: 'name-of-techdocs-storage-bucket'      region: ${AWS_REGION}      credentials:        roleArn: arn:aws:iam::123456789012:role/my-backstage-role

참고: 역할을 가정하려면 기본 자격 증명이 AWS.config.credentials에 이미 설정되어 있어야 해요. AWS에서 역할 가정에 대해 자세히 읽어 보세요.

이게 전부예요!

이제 Backstage 앱이 TechDocs용 AWS S3를 사용해 정적으로 생성된 문서 파일을 저장하고 읽을 준비가 됐어요. 앱의 백엔드를 시작하면 로그에서 techdocs info Successfully connected to the AWS S3 bucket를 볼 수 있어야 해요.

TechDocs로 Azure Blob Storage 컨테이너 구성하기

Azure Blob Storage가 포함된 다음 단계에 대한 최신 지침은 공식 Azure Blob Storage 문서를 따르세요.

app-config.yaml에서 techdocs.publisher.type 구성을 설정

techdocs.publisher.type을 'azureBlobStorage'로 설정하세요.

techdocs:  publisher:    type: 'azureBlobStorage'

Azure Blob Storage 컨테이너 만들기

TechDocs 사이트용 전용 컨테이너를 만드세요. 공식 문서를 참고하세요.

TechDocs는 이 컨테이너에 문서를 게시하고 여기에서 파일을 가져와 Backstage에서 문서를 서빙해요. 컨테이너 이름은 전 세계적으로 고유하다는 점에 유의하세요.

app-config.yaml에서 techdocs.publisher.azureBlobStorage.containerName 구성을 방금 만든 컨테이너 이름으로 설정하세요.

techdocs:  publisher:    type: 'azureBlobStorage'    azureBlobStorage:      containerName: 'name-of-techdocs-storage-container'

3a. (권장) 환경 변수를 사용한 인증

Backstage의 Azure Blob Storage 클라이언트는 DefaultAzureCredential이 제공하는 모든 자격 증명 유형을 지원해요. 즉 서비스 주체용 환경 변수, 관리 ID(managed identity) 및 기본 자격 증명 체인의 기타 방법을 사용해 인증할 수 있어요.

Kubernetes에 배포할 때는 Azure Workload Identity Federation을 사용해 비밀을 관리하지 않고 Backstage 워크로드에 스토리지 계정 접근 권한을 부여할 수 있어요. 관리 ID가 있는 Azure Virtual Machines나 Azure Kubernetes Service(AKS)에서 실행 중이라면 accountName과 containerName 외에 추가 구성이 필요하지 않을 수 있어요. 다른 시나리오에서는 다음을 설정해 서비스 주체를 사용할 수 있어요.

AZURE_CLIENT_ID
AZURE_TENANT_ID
AZURE_CLIENT_SECRET

app-config.yaml의 예시 구성:

techdocs:  publisher:    type: 'azureBlobStorage'    azureBlobStorage:      containerName: 'name-of-techdocs-storage-container'      credentials:        accountName: ${TECHDOCS_AZURE_BLOB_STORAGE_ACCOUNT_NAME}

참고: 사용하는 계정이나 자격 증명은 필요에 따라 객체를 읽고, 쓰고, 삭제하려면 컨테이너에 Storage Blob Data Owner 역할이 있어야 해요. 외부 게시자를 사용한다면 Storage Blob Data Reader 역할로 충분해요.

자세한 내용은 Azure Identity 문서와 Kubernetes용 Workload Identity Federation을 참고하세요.

3b. app-config.yaml을 사용한 인증

(3a)를 선호하지 않고 선택적으로 키 기반 접근을 사용하고 싶다면 다음 단계를 따를 수 있어요.

자격 증명을 얻으려면 Azure Portal에 접속해 "Settings > Access Keys"로 이동해 스토리지 계정 이름과 기본 키(Primary Key)를 얻으세요. 자세한 내용은 https://docs.microsoft.com/en-us/rest/api/storageservices/authorize-with-shared-key 을 참고하세요.

techdocs:  publisher:    type: 'azureBlobStorage'    azureBlobStorage:      containerName: 'name-of-techdocs-storage-bucket'      credentials:        accountName: ${TECHDOCS_AZURE_BLOB_STORAGE_ACCOUNT_NAME}        accountKey: ${TECHDOCS_AZURE_BLOB_STORAGE_ACCOUNT_KEY}

어느 경우든 컨테이너와 그 아래의 모든 TechDocs 객체에 접근하는 데 사용하는 계정이나 자격 증명에는 필요에 따라 객체를 읽고, 쓰고, 삭제할 수 있도록 Storage Blog Data Owner 역할을 적용해야 해요. 외부 게시자를 사용하는 경우에는 Storage Blob Data Reader 역할로 충분해요.

이게 전부예요!

이제 Backstage 앱이 TechDocs용 Azure Blob Storage를 사용해 정적으로 생성된 문서 파일을 저장하고 읽을 준비가 됐어요. 앱의 백엔드를 시작하면 로그에서 techdocs info Successfully connected to the Azure Blob Storage container를 볼 수 있어야 해요.

TechDocs로 OpenStack Swift 컨테이너 구성하기

OpenStack Storage가 포함된 다음 단계에 대한 최신 지침은 공식 OpenStack Api 문서를 따르세요.

app-config.yaml에서 techdocs.publisher.type 구성을 설정

techdocs.publisher.type을 'openStackSwift'로 설정하세요.

techdocs:  publisher:    type: 'openStackSwift'

OpenStack Swift Storage 컨테이너 만들기

TechDocs 사이트용 전용 컨테이너를 만드세요. 공식 문서를 참고하세요.

app-config.yaml에서 techdocs.publisher.openStackSwift.containerName 구성을 방금 만든 컨테이너 이름으로 설정하세요.

techdocs:  publisher:    type: 'openStackSwift'    openStackSwift:      containerName: 'name-of-techdocs-storage-container'

app-config.yaml을 사용한 인증

app-config.yaml의 구성을 컨테이너 이름을 가리키도록 설정하세요.

자세한 내용은 https://docs.openstack.org/api-ref/identity/v3/?expanded=password-authentication-with-unscoped-authorization-detail,authenticating-with-an-application-credential-detail#authenticating-with-an-application-credential 을 참고하세요.

techdocs:  publisher:    type: 'openStackSwift'    openStackSwift:      containerName: 'name-of-techdocs-storage-bucket'      credentials:        id: ${OPENSTACK_SWIFT_STORAGE_APPLICATION_CREDENTIALS_ID}        secret: ${OPENSTACK_SWIFT_STORAGE_APPLICATION_CREDENTIALS_SECRET}      authUrl: ${OPENSTACK_SWIFT_STORAGE_AUTH_URL}      swiftUrl: ${OPENSTACK_SWIFT_STORAGE_SWIFT_URL}

이게 전부예요!

이제 Backstage 앱이 TechDocs용 OpenStack Swift Storage를 사용해 정적으로 생성된 문서 파일을 저장하고 읽을 준비가 됐어요. 앱의 백엔드를 시작하면 로그에서 techdocs info Successfully connected to the OpenStack Swift Storage container를 볼 수 있어야 해요.

보너스: 이전 OpenStack Swift 구성에서 마이그레이션

여기 이전 OpenStack Swift 구성이 있다고 가정해 보겠어요.

techdocs:  publisher:    type: 'openStackSwift'    openStackSwift:      containerName: 'name-of-techdocs-storage-bucket'      credentials:        username: ${OPENSTACK_SWIFT_STORAGE_USERNAME}        password: ${OPENSTACK_SWIFT_STORAGE_PASSWORD}      authUrl: ${OPENSTACK_SWIFT_STORAGE_AUTH_URL}      keystoneAuthVersion: ${OPENSTACK_SWIFT_STORAGE_AUTH_VERSION}      domainId: ${OPENSTACK_SWIFT_STORAGE_DOMAIN_ID}      domainName: ${OPENSTACK_SWIFT_STORAGE_DOMAIN_NAME}      region: ${OPENSTACK_SWIFT_STORAGE_REGION}

1단계: 자격 증명 키 변경

새 SDK는 OpenStack 인증에 Application Credentials를 사용하므로 credentials.username 키를 credentials.id로, credentials.password를 credentials.secret으로 변경하고 여기에 Application Credential ID와 secret을 사용해야 해요. 자격 증명에 대한 자세한 내용은 여기를 보세요.

2단계: 사용하지 않는 키 제거

새 SDK는 이전 방식의 인증을 사용하지 않으므로 openStackSwift.keystoneAuthVersion, openStackSwift.domainId, openStackSwift.domainName, openStackSwift.region 키가 필요 없어요. 이들을 제거할 수 있어요.

3단계: Swift URL 추가

새 SDK는 Swift에 연결하기 위해 OpenStack Swift 연결 URL이 필요해요. 그래서 openStackSwift.swiftUrl이라는 새 키를 추가하고 여기에 OpenStack Swift URL을 넣어야 해요. 예시 URL은 다음과 같아야 해요. https://example.com:6780/swift/v1

이게 전부예요!

새 구성은 다음과 같아야 해요!

techdocs:  publisher:    type: 'openStackSwift'    openStackSwift:      containerName: 'name-of-techdocs-storage-bucket'      credentials:        id: ${OPENSTACK_SWIFT_STORAGE_APPLICATION_CREDENTIALS_ID}        secret: ${OPENSTACK_SWIFT_STORAGE_APPLICATION_CREDENTIALS_SECRET}      authUrl: ${OPENSTACK_SWIFT_STORAGE_AUTH_URL}      swiftUrl: ${OPENSTACK_SWIFT_STORAGE_SWIFT_URL}