Skip to content

Commit

Permalink
docs(cdk-ops): translate data-warehouse.md → ja
Browse files Browse the repository at this point in the history
- Translates `docs/data-warehouse.md` into Japanese. Also refines the
  English version.

issue codemonger-io#30
  • Loading branch information
kikuomax committed Oct 19, 2022
1 parent 9b61fec commit 81cea1e
Show file tree
Hide file tree
Showing 2 changed files with 127 additions and 4 deletions.
122 changes: 122 additions & 0 deletions cdk-ops/docs/data-warehouse.ja.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
[English](./data-warehouse.md) / 日本語

# アクセスログ用のデータウェアハウス

このCDKスタックはアクセスログ用のデータウェアハウスを確保します。
データウェアハウスは[Amazon Redshift Serverless](https://aws.amazon.com/redshift/redshift-serverless/)を使って実現しています。

## AWSアーキテクチャ

以下の図はデータウェアハウスのAWSアーキテクチャを表しています。

![データウェアハウスのAWSアーキテクチャ](./data-warehouse-aws-architecture.png)

### Amazon CloudFront

`Amazon CloudFront`は我々のウェブサイトのコンテンツを配布しアクセスログを[`Amazon S3 access log bucket`](#amazon-s3-access-log-bucket)に保存します。

### Amazon S3 access log bucket

`Amazon S3 access log bucket`[Amazon S3 (S3)](https://aws.amazon.com/s3/)のバケットで、[`Amazon CloudFront`](#amazon-cloudfront)が作成したアクセスログを格納します。
このバケットはアクセスログファイルがPUTされた際、[`MaskAccessLogs queue`](#maskaccesslogs-queue)にイベントを送ります。

### MaskAccessLogs queue

`MaskAccessLogs queue`[Amazon Simple Queue Service (SQS)](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/welcome.html)のキューで、[`MaskAccessLogs`](#maskaccesslogs)を呼び出します。
[`Amazon S3 access log bucket`](#amazon-s3-access-log-bucket)はアクセスログファイルがPUTされた際、このキューにイベントを送ります。

### MaskAccessLogs

`MaskAccessLogs`[AWS Lambda (Lambda)](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html)関数で、[`Amazon S3 access log bucket`](#amazon-s3-access-log-bucket)のアクセスログを変換します。
この関数は[CloudFrontアクセスログ](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/AccessLogs.html#LogFileFormat)内のIPアドレス(`c-ip``x-forwarded-for`)をマスクします。
この関数はアクセスログレコードの順序を保持するために行番号のカラムも追加します。
この関数は変換結果を[`Amazon S3 transformed log bucket`](#amazon-s3-transformed-log-bucket)に保存します。
[`Amazon S3 access log bucket`](#amazon-s3-access-log-bucket)はアクセスログファイルをフラットに展開するのに対して、この関数はアクセスログレコードの年月日に相当するフォルダ階層を作成します。
このフォルダ構造は[`LoadAccessLogs`](#loadaccesslogs)が特定の日付のアクセスログをバッチで処理するのに役立ちます。

### Amazon S3 transformed log bucket

`Amazon S3 transformed log bucket`はS3バケットで、[`MaskAccessLogs`](#maskaccesslogs)が変換したアクセスログを格納します。
このバケットは変換されたアクセスログファイルがPUTされると[`DeleteAccessLogs queue`](#deleteaccesslogs-queue)にイベントを送ります。

### DeleteAccessLogs queue

`DeleteAccessLogs queue`はSQSキューで、[`DeleteAccessLogs`](#deleteaccesslogs)を呼び出します。
[`Amazon S3 transformed log bucket`](#amazon-s3-transformed-log-bucket)は変換されたアクセスログがPUTされるとこのキューにイベントを送ります。

### DeleteAccessLogs

`DeleteAccessLogs`はLambda関数で、[`MaskAccessLogs`](#maskaccesslogs)が変換し[`Amazon S3 transformed log bucket`](#amazon-s3-transformed-log-bucket)に保存したアクセスログファイルを[`Amazon S3 access log bucket`](#amazon-s3-access-log-bucket)から削除します。

### Amazon Redshift Serverless

`Amazon Redshift Serverless`[Amazon Redshift Serverless](https://aws.amazon.com/redshift/)のリソースをまとめたもので、データウェアハウスのコアとなります。

ひとつの[ファクトテーブル](https://en.wikipedia.org/wiki/Fact_table)
- `access_log`

5つの[ディメンジョンテーブル](https://en.wikipedia.org/wiki/Dimension_(data_warehouse))からなります。
- `referer`
- `page`
- `edge_location`
- `user_agent`
- `result_type`

`Amazon Redshift Serverless`のノードはプライベートサブネットに配置されます。
Lambda関数([`PopulateDwDatabase`](#populatedwdatabase), [`LoadAccessLogs`](#loadaccesslogs), [`VacuumTable`](#vacuumtable))は[`Amazon Redshift Data API`](#amazon-redshift-data-api)を介して`Amazon Redshift Serverless`を操作します。

[Amazon Redshift Serverlessネームスペース](https://docs.aws.amazon.com/redshift/latest/mgmt/serverless-workgroup-namespace.html)のデフォルトロール([`Redshift namespace role`](#redshift-namespace-role))は[`Amazon S3 transformed log bucket`](#amazon-s3-transformed-log-bucket)からオブジェクトを読み込むことができます。
`Amazon Redshift Serverless`[`Gateway endpoint`](#gateway-endpoint)を介して[`Amazon S3 transformed log bucket`](#amazon-s3-transformed-log-bucket)にアクセスします。

このCDKスタックは`Amazon Redshift Serverless`を確保する際に管理ユーザーを作成します。
[`AWS Secrets Manager`](#aws-secrets-manager)は管理ユーザーのパスワードを生成・管理します。

### Redshift namespace role

`Redshift namespace role`[AWS Identity and Access Management (IAM)](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html)のロールで、[`Amazon Redshift Serverless`](#amazon-redshift-serverless)のネームスペースのデフォルトロールであり[`Amazon S3 transformed log bucket`](#amazon-s3-transformed-log-bucket)からオブジェクトを読み込むことができます。

### Gateway endpoint

`Gateway endpoint`[`Amazon Redshift Serverless`](#amazon-redshift-serverless)[`Amazon S3 transformed log bucket`](#amazon-s3-transformed-log-bucket)の間のトラフィックがインターネットに出て行かないようにします。
詳しくは["Enhanced VPC routing in Amazon Redshift" - *Amazon Redshift Management Guide*](https://docs.aws.amazon.com/redshift/latest/mgmt/enhanced-vpc-routing.html)をご参照ください。

### AWS Secrets Manager

`AWS Secrets Manager`[`Amazon Redshift Serverless`](#amazon-redshift-serverless)の管理ユーザーのパスワードを生成・管理します。
[*AWS Secrets Manager User Guide*](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)もご参照ください。

残念ながら、`AWS Secrets Manager`が管理するシークレットは[`Amazon Redshift Serverless`](#amazon-redshift-serverless)の管理パスワードと同期していません(初回生成時を除く)。
なので`AWS Secrets Manager`が新しいシークレットを生成してしまった際には、[`Amazon Redshift Serverless`](#amazon-redshift-serverless)の管理パスワードを手作業でリセットしなければなりません。

### Amazon Redshift Data API

`Amazon Redshift Data API`[`Amazon Redshift Serverless`](#amazon-redshift-serverless)のクライアントをデータベースへの接続を管理することから解放してくれます。
詳しくは["Using the Amazon Redshift Data API" - *Amazon Redshift Management Guide*](https://docs.aws.amazon.com/redshift/latest/mgmt/data-api.html)をご参照ください。

### PopulateDwDatabase

`PopulateDwDatabase`はLambda関数で、アクセスログを格納するデータベースとテーブルを[`Amazon Redshift Serverless`](#amazon-redshift-serverless)に作成します。
この関数は[`Amazon Redshift Serverless`](#amazon-redshift-serverless)の管理クレデンシャルを[`AWS Secrets Manager`](#aws-secrets-manager)から取得します。
管理者(`Admin`)はこのCDKスタックをデプロイした後にこの関数を呼び出さなければなりません。

### Amazon EventBridge

`Amazon EventBridge`は毎日午前2時(UTC)に[`LoadAccessLogs`](#loadaccesslogs)を実行する[Amazon EventBridgeのルール](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-create-rule-schedule.html)を定義します。

### LoadAccessLogs

`LoadAccessLogs`はLambda関数で、指定した日付のアクセスログを[`Amazon Redshift Serverless`](#amazon-redshift-serverless)に読み込みます。
この関数はアクセスログの読み込みが終了すると[`AWS Step Functions`](#aws-step-functions)を実行します。
[`Amazon EventBridge`](#amazon-eventbridge)は1日に1回この関数を実行します。

この関数は[`Amazon EventBridge`](#amazon-eventbridge)から呼び出すことを想定していますが、適切なペイロードを与えて手作業で実行することもできます。

### AWS Step Functions

`AWS Step Functions`[`Amazon Redshift Serverless`](#amazon-redshift-serverless)のすべてのテーブル(`access_log`, `referer`, `page`, `edge_location`, `user_agent`, `result_type`)に対して[`VacuumTable`](#vacuumtable)を実行する[AWS Step Functionsのステートマシン](https://docs.aws.amazon.com/step-functions/latest/dg/welcome.html)を定義します。
[`VACUUM` SQLコマンド](https://docs.aws.amazon.com/redshift/latest/dg/r_VACUUM_command.html)の実行は同時に1つしか許されていないので、`AWS Step Functions`はテーブルをひとつずつ[`VacuumTable`](#vacuumtable)で処理します。

### VacuumTable

`VacuumTable`はLambda関数で、[`VACUUM` SQLコマンド](https://docs.aws.amazon.com/redshift/latest/dg/r_VACUUM_command.html)を指定したテーブルに対して実行します。
この関数は[`Amazon Redshift Serverless`](#amazon-redshift-serverless)の管理クレデンシャルを[`AWS Secrets Manager`](#aws-secrets-manager)から取得します。
9 changes: 5 additions & 4 deletions cdk-ops/docs/data-warehouse.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
English / 日本語
English / [日本語](./data-warehouse.ja.md)

# Data warehouse for access logs

Expand Down Expand Up @@ -46,11 +46,12 @@ This bucket sends an event to [`DeleteAccessLogs queue`](#deleteaccesslogs-queue

### DeleteAccessLogs

`DeleteAccessLogs` is a Lambda function that deletes an access logs file in [`Amazon S3 access log bucket`](#amazon-s3-access-log-bucket), which has been transformed by [`MaskAccessLogs`](#maskaccesslogs) and saved in [`Amazon S3 transformed log bucket`](#amazon-s3-transformed-log-bucket).
`DeleteAccessLogs` is a Lambda function that deletes an access logs file from [`Amazon S3 access log bucket`](#amazon-s3-access-log-bucket), which [`MaskAccessLogs`](#maskaccesslogs) has transformed and saved in [`Amazon S3 transformed log bucket`](#amazon-s3-transformed-log-bucket).

### Amazon Redshift Serverless

`Amazon Redshift Serverless` is a bundle of [Amazon Redshift Serverless](https://aws.amazon.com/redshift/) resources, which is the core of the data warehouse.

It has one [fact table](https://en.wikipedia.org/wiki/Fact_table),
- `access_log`

Expand All @@ -64,7 +65,7 @@ and five [dimension tables](https://en.wikipedia.org/wiki/Dimension_(data_wareho
Nodes of `Amazon Redshift Serverless` reside in a private subnet.
Lambda functions, [`PopulateDwDatabase`](#populatedwdatabase), [`LoadAccessLogs`](#loadaccesslogs), and [`VacuumTable`](#vacuumtable) operate `Amazon Redshift Serverless` via [`Amazon Redshift Data API`](#amazon-redshift-data-api).

The default role of the Amazon Redshift Serverless namespace ([`Redshift namespace role`](#redshift-namespace-role)) can read objects from [`Amazon S3 transformed log bucket`](#amazon-s3-transformed-log-bucket).
The default role of the [Amazon Redshift Serverless namespace](https://docs.aws.amazon.com/redshift/latest/mgmt/serverless-workgroup-namespace.html) ([`Redshift namespace role`](#redshift-namespace-role)) can read objects from [`Amazon S3 transformed log bucket`](#amazon-s3-transformed-log-bucket).
`Amazon Redshift Serverless` accesses [`Amazon S3 transformed log bucket`](#amazon-s3-transformed-log-bucket) through [`Gateway endpoint`](#gateway-endpoint).

This CDK stack creates an admin user when it provisions `Amazon Redshift Serverless`.
Expand All @@ -82,7 +83,7 @@ Please refer to ["Enhanced VPC routing in Amazon Redshift" - *Amazon Redshift Ma
### AWS Secrets Manager

`AWS Secrets Manager` generates and manages the password of the admin user of [`Amazon Redshift Serverless`](#amazon-redshift-serverless).
Please refer to [*AWS Secrets Manager User Guide*](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html).
Please also refer to [*AWS Secrets Manager User Guide*](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html).

Unfortunately, the secret managed by `AWS Secrets Manager` does not sync with the admin password of [`Amazon Redshift Serverless`](#amazon-redshift-serverless) except for the first time it is generated.
So you have to manually reset the admin password of [`Amazon Redshift Serverless`](#amazon-redshift-serverless) in case `AWS Secrets Manager` generates a new secret.
Expand Down

0 comments on commit 81cea1e

Please sign in to comment.