CD3 Automation ToolkitでOCIリソースをExcelから爆速構築！その1 概要説明とリソース作成編

# 対象
Excel大好き！自動化大好き！なOCIユーザーを対象としています。

"CD3 Automation Toolkit"でOCIリソースをExcelから爆速構築！シリーズです。
その２ リソース出力編は[こちら](https://qiita.com/harukb/items/fbc02a02c8fb39db7ec1) 

# はじめに
みなさんはこのような悩みをお持ちではないでしょうか

- PoCでクイックにOCIの設計/構築を行いたい
- 構築後のチェック、目が痛い
- Terraformで書き始めるもののコード設計、実装、テストで結局時間はかかる
- そして、同じことの繰り返し。。。。

そんな皆様向けに、オラクル（Oracle Corporation) 提供によるOSSツール"CD3 Automation toolkit"というツールを個人的に軽く触ってみたので紹介します。
 （CD3は"Cloud Deployment Design Deliverable"の略とのこと。）

このツールによりExcelからのリソース構築、あるいは構築済リソースのExcel出力がコマンドで可能になるため、手作業部分の省力化を図ることが可能です。
※またTerraform管理対象とせずとも、棚卸目的にまずは手動構築済リソースのExcel出力だけの利用も可能です。

食欲の秋ということでこれを機に、食わず嫌いの方はOCIを少しでもかじってみませんか？



# 注意事項
- この記事では、CD3の説明、簡易な導入手順、操作手順や検証した所感を記載します
- 個人的な経験則に基づいた記載ですので、ご利用はあくまでも自己責任にてお願いします
- 設計内容はあくまでもCD3実行のためのサンプルです
- OSSライセンスのため、お問い合わせは公式の[Slackチャンネル](https://oracle-devrel.github.io/cd3-automation-toolkit/latest/queries/)をご利用ください
- 本家のCD3サイトは非常に分かりやすく情報も豊富なのでぜひ活用を！

# 概要
## CD3 Automation Toolkitとは
- Oracle Corporation提供のPythonによるOSSツール 
[公式サイトはこちら](https://oracle-devrel.github.io/cd3-automation-toolkit/latest/)　
[概要動画はこちら](https://youtu.be/bYiUnT_WUAo?si=EBTTIl1uJm1qsZbx)
- コマンドを実行することで、ExcelファイルからTerraformコード自動生成、またその逆のOCIリソースからExcelファイル等にリソース情報を自動出力
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/607651/286fd5f0-20ed-d15d-a82f-740a0aa34d23.png)
図は[CD3公式サイト](https://oracle-devrel.github.io/cd3-automation-toolkit/latest/cd3-overview/)より。
- 本年のOracle Cloud World 2024でもCD3のセッションが実施されたようです！
- 更新頻度もかなり多く活発です
- このページでは以降、CD3と記載させていただきます


## 対応ユースケース
### OCI でリソースを作成および管理する (Greenfield workflow)
- リソースを新規構築するテナンシー or 既存のリソースを管理対象としない場合向け
    - ExcelファイルからTerraform実行に必要なtfvarsファイルをCD3で生成・再生成する
    - 生成されたtfvarsを利用してTerraformからOCIリソースの生成を行う
    
### OCI でのリソースのエクスポートと管理 (Non-Greenfield Workflow)
- 既存のリソースも含めて新たにTerraform管理対象とする場合向け
    - OCIからCD3を利用して既存リソースのExcelファイルやTerraform管理に必要なStateファイルを出力する
    - CD3を利用してimportコマンドを含むShell Scriptを生成する
    - Stateファイルを更新するためにShell Scriptを実行する

### 注意
- 既存でTerraform管理している場合には、既存のコードとの競合が発生するため向かないかもしれません
- その場合も、もちろんリソースの棚卸目的に、OCIからCD3を利用して既存リソースのExcelファイルを出力するだけの単独利用は可能です。（それだけでも大きなメリットがあると思います）

## 実行
以下の2通りのうち、OCI Resource Managerでの方式が推奨されています。今回検証した際にも前者を利用しました。
- 【推奨方式】OCI Resource ManagerでComputeインタンス上にコンテナを自動デプロイ
- GitHubからのソースコード入手と手動によるコンテナのビルド＆実行

## CD3の主な機能
見た限りなので、完全ではないかもしれません。
- ExcelファイルからTerraform 構成ファイルの出力
- OCIリソースからExcelファイルやインポート用Shell Scipt等の出力
- ServiceごとにTerraformコードをグループ化出力
- TerraformのStateファイルをOCI Object StorageのBucketに格納
- OCI Resource ManagerにTerraformコードをアップロード
- ユーザーによるパラメータ列の拡張も可能なExcelテンプレート
- 入力値の簡易なバリデーション
- CD3のAutomation ToolkitのJenkinsから顧客環境のJenkinsへのジョブ移行

## 主な対象リソース
- [Services Supported](https://oracle-devrel.github.io/cd3-automation-toolkit/latest/supportedservices/)
リソース単位では結構揃ってますね。

**注意**
例えばMonitoringは対象ですが、その中でもAlarms RuleのOverridesが現時点では対応していなかったりするようです。そう多くはないかと思いますが、未対応のパラメータは他にもあるかもしれません。あらかじめ必要なリソースのExcelパラメータシートを確認することをお勧めします。

# 導入
## 前提条件
- OCIの設計、構築に関する基本的な知識は必要です
- LinuxのOSコマンド操作やOCI CloudShellの操作に関しても同様です

- Terraformコーディングは毎回必要という訳ではないのですが、手動実装の必要もあり得るためTerraformに関する知識は基本的な事項を押さえておく必要はあります

## 手順
まとめようと思いましたが（どこの会社かと二度見するぐらい:eyes:）CD3の公式のインストールガイド[（Install CD3）](https://oracle-devrel.github.io/cd3-automation-toolkit/latest/install-cd3/)がユーザーフレンドリーで丁寧なのでそちらで進めましょう。ドキュメントだけでなくYoutubeの動画でも解説があります。後はブラウザで自動翻訳さえできたら問題ないと思われます。

# 検証
## 今回の構築イメージ
黄色の網掛けのリソースがCD3(Terraform)での構築対象
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/607651/dff38f91-3410-2246-2d77-7320653e79f9.png)


- CD3実行環境は公式に沿って完了済。CD3実行環境VMは別のVCNに配置し、SSHで接続後にCD3用のコンテナが起動できることを確認済
- コンパートメントに関して
     - ネットワークリソースに関するCompartment名は例として"Network"で作成済。今回CD3によりネットワークリソースはこの中に配置する
    - Bucketの配置先のCompartment名は"AppDev"で作成済
- リージョンに関して
    - Home Regionはus-phoenix-1、Remote Regionはap-tokyo-1
- ポリシーに関して
    - CloudShellの実行に必要なポリシーやネットワーク設定もすでに実施済
    - Terrform実行に必要なIAM PolicyもCD3のガイドに基づいてすでに付与済
    - 今回はクロスリージョンのBucket作成を含むので以下のサービスポリシーも付与済
      Allow service objectstorage-(対向リージョン名) to manage object-family in tenancy　



## 検証内容
- 既存リソースの取り込み必要のない前述のユースケースパターン "Greenfield workflow"環境にて、Excelファイルから正常にリソースが作成と削除、更新がされるか検証する

- 作成対象リソースは次の通り
    - Phoenixリージョン（Home）
        - VCN
        - Subnet
        - Route Table
        - Security List
        - Compute　☆
        - Object Storage - Bucket　★
    
    - Tokyoリージョン（Remote）
        - Object Storage - Bucket ★
    
# 検証シナリオ
その１はここまで
- Excelを記入してアップロードし、当ツールで"create resources"を実行
- 生成されたTerraformコードを利用して構築（Apply）実行する  
------------------------------------------------------
後日アップ予定
-  構築したリソースをExcelファイルに出力して想定どおりか確認する
-  Excelファイルより、リソース更新（☆のセル値更新）とリソース削除（★の削除）操作ののちファイル更新
-  再アップロードして再度"create resources"の実行
- 生成されたTerraformコードを利用して構築（Apply）実行する

# 操作手順（ざっくり）
## リソース作成

### Excelテンプレートのダウンロード
CD3サイトの [Overview>Excel Templates](https://oracle-devrel.github.io/cd3-automation-toolkit/latest/excel-templates/)よりリンク先のGitHubリポジトリに進み、ページの右側にある "Download row files"アイコンよりテンプレートファイルをダウンロードします。

ここではシンプルにCD3-Blank-template.xlsxを利用しています。
他にもOCI Network FirewallやOracle Cloud Observability and Management（O&M）向け、Center for Internet Security (CIS)に適用したテンプレートもあるようです。
### Excelテンプレートへの値入力

CD3-Blank-template.xlsxから必要な値を記載します。
なお、ファイル名はリネームすることも可能でした。
ここでは"CD3-Blank-template_terraform_test_1.xlsx"としています。

作成リソースの全ては記載割愛しますが、分かりづらかったポイントのみ解説します。
Excelのヘッダに説明があるものもあれば手探りのものもあります。
#### ヒント ####
迷ったら手動で作成して、Export機能でExcelにリバース出力して確認するという方法も取れます！

#### シート（部分抜粋） ####
■VCN
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/607651/8df09c58-aa25-ff76-155b-3c182fda7d84.png)

■Subnet
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/607651/bfefbb57-92cd-9089-429e-a226367e10e8.png)

■Route Table
Route Destination Object、Destination Typeはこんな表記
例) sgw:vcn-test_sgw,SERVICE_CIDR_BLOCK
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/607651/57e5b362-29e6-96f2-c9c6-8f2f564c3e36.png)

■Security List
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/607651/e2303bbb-3090-0ead-3c1f-94d4df73101d.png)


■Compute
Network Details、Source Details、Shapeはこんな表記
例）Network@vcn-test::subnet-pri-test,image::Oracle-Linux-9-4-2024-07-31-0,VM.Standard3.Flex::2
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/607651/52863d3c-5825-cac2-a48c-dec3ac6ad98a.png)

■Buckets
Retention Rules、Lifecycle Target and Action、Lifecycle Rule Periodはこんな表記
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/607651/6452eadb-dc07-4a4e-f385-1cde63d14740.png)


### OCI CloudShellへのアップロード
ローカルのExcelファイルをOCI CloudShellのHomeにドラッグしてアップロードします。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/607651/d809d749-9f40-3bb2-156f-b445d836771b.png)

### Computeへの転送

#### 実行例
```
xxx@cloudshell:~ (us-phoenix-1)$ scp -i .ssh/cd3/(ssh-key-xxx.key) ~/CD3-Blank-template_terraform_test_1.xlsx cd3user@10.2.0.54:/cd3user/mount_path/(tenancy name)
FIPS mode initialized
CD3-Blank-template_terraform_test_1.xlsx         
```

※  CD3コンテナのtenanciesフォルダは、Computeの/cd3user/mount_pathフォルダにマップされます（[ドキュメント](https://docs.oracle.com/ja/learn/oci-cd3-greenfield/index.html#task-31-prepare-excel-and-variables-file)）

### コンテナの起動と接続
#### コンテナ接続
```
#Computeに接続
ssh -i .ssh/cd3/(ssh-key-xxx.key) cd3user@10.2.0.54
#コンテナIDの確認(xxxxxxxx部)と開始
sudo podman ps -a
sudo podman start xxxxxxxx

# ログイン
sudo podman exec -it cd3_toolkit bash
```
### 設定ファイル名の更新（変更がある場合のみ）
```
vi /cd3user/tenancies/(tenancy name)/(tenancy name)_setUpOCI.properties
```
設定は23行目位あたり（※）
また今回はリソース作成なのでworkflow_type=create_resourcesとなります。
```
 #path to cd3 excel eg /cd3user/tenancies/<customer_name>/CD3-Customer.xlsx
 cd3file=/cd3user/tenancies/(tenancy name)/CD3-Blank-template_terraform_1.xlsx ※
  
 #specify create_resources to create new resources in OCI(greenfield workflow)
 #specify export_resources to export resources from OCI(non-greenfield workflow)
 workflow_type=create_resources
 ```

### CD3の実行
今回はVCN、Subnet、Route Table、Security List、Compute、Bucketの単位で順にファイル出力とTerraform Plan/Applyを実行していきます。

### Networkリソースの作成
まずはNetworkリソースとしてVCN、Subnet、Route Table、Security Listを作成します。

#### ツールの起動
  ```
cd /cd3user/oci_tools/cd3_automation_toolkit/
python setUpOCI.py /cd3user/tenancies/(tenancy name)/(tenancy name)_setUpOCI.properties
 ```
#### 入力値のバリデーション
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/607651/81a0e86b-fdf8-215f-8686-f94217199d29.png)

 _0. Validate CD3 > 6. Validate Network(VCNs, SubnetsVLANs, DHCP, DRGs)_  
 と進んでいくとチェックが開始されます。エラーが表示されないことを確認します。
 ```
Summary:
=======
There are no errors in CD3. Please proceed with TF Generation
 ```
#### 注意 ####
チェックは基本的な値検証であり、ネットワークのリソース間の整合性チェックやComputeのImageの存在チェック等の高度な内容はあまり期待しない方が良いかもしれません。

#### CD3でのコード生成 #### 
##### ツールの起動 #####
  ```
cd /cd3user/oci_tools/cd3_automation_toolkit/
python setUpOCI.py /cd3user/tenancies/(tenancy name)/(tenancy name)_setUpOCI.properties
 ``` 
##### VCN、Subnetの*.auto.tfvars出力実行 #####

_4.  Network > 1. Create Network_
を選択するとVCN、Subnetの*.auto.tfvarsが後述のnetworkディレクトリに出力されます。

##### Route Table、Security Listの*.auto.tfvars出力実行 #####

3\. Security Rules,4. Route Rulesの両方を指定します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/607651/398362f9-1266-4659-eb73-e6f234718e36.png)

それぞれのAddを行うため2を選択します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/607651/61e02604-a8cf-3b28-764c-7550a7440b84.png)


正常に処理が完了すると、*.auto.tfvarsが後述のnetworkディレクトリに出力されます。

#### TerraformによるNetworkリソース作成 ####
##### Networkリソースディレクトリへの移動 #####
```
cd /cd3user/tenancies/(Tenancy name)/terraform_files/(Region name)/network
```
networkリソース向けのディレクトリに*.auto.tfvarsが作成されていることを確認します。

##### TerraformによるNetworkリソース作成 #####
実行するTerraformコマンドの意味はきちんと把握しておきましょう！大事！
```
terraform init
terraform plan
```
plan後の計画を確認します。
想定出力（新規作成10件、変更0件、削除0件）
```
Plan: 10 to add, 0 to change, 0 to destroy.
```
10件の内容が意図通りか、Excel入力時のミスやTerraformによる想定外の解釈はないかを確認を行います。
問題なければリソースを作成します

```
terraform apply
```
途中で"yes"を挟みつつ、正常にリソースが作成されると以下のようにメッセージが表示されます。
```
Apply complete! Resources: 10 added, 0 changed, 0 destroyed.
```
##### リソース生成の確認（目視） #####
まずは目視で軽く確認。リソースは作成されているようですね。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/607651/6f473181-60b6-8bc7-e8d1-5d9a7dbccff3.png)

### Computeリソースの作成
次にインスタンスを2個作成します。手順は上記のネットワークと同じ流れなので要点だけ記載します。

#### 入力値のバリデーション
- Validationメニューは"8.  Validate Instances"を選択
#### CD3でのコード生成
- コード生成のメニューは"7.  Compute" > "2. Add/Modify/Delete Instances/Boot Backup Policy"を選択

#### TerraformによるComputeリソース作成 ####
- Computeリソースディレクトリは以下のパス
```
cd /cd3user/tenancies/(Tenancy name)/terraform_files/(Region name)/compute
```
後はネットワークと同じ操作です。

### Object Storageリソースの作成
最後にBucketを2個作成します。それに加えてBucketに付与する保持ルール、ライフサイクルポリシーも作成します。手順はこちらも上記のネットワークと同じ流れなので要点だけ記載します。

#### 入力値のバリデーション
- Validationメニューは"11. Validate Buckets"を選択
#### CD3でのコード生成
- コード生成のメニューは"8.  Storage" > "3. Add/Modify/Delete Object Storage Buckets"を選択

#### TerraformによるObjectリソース作成 ####
- Objectリソースディレクトリは以下のパス
※ 今回Bucketはus-phoenix-1とap-tokyo-1に作成しているので、それぞれのリージョンのossディレクトリごとにTerraformコマンドを実行します。
```
cd /cd3user/tenancies/(Tenancy name)/terraform_files/(Region name)/oss
```
後はネットワークと同じ操作です。

# まとめ（その１） #
ExcelからCD3を利用してTerraformコード生成、ならびにTerraformコマンドを利用して
短時間にリソース構築ができることを確認しました。
次回は実際に構築したリソースをExcelにExportし、また更新したExcelからリソース反映を実施したいと思います。


# 参考情報
[CD3サイト](https://oracle-devrel.github.io/cd3-automation-toolkit/latest/cd3-overview/)
[Help Center](https://docs.oracle.com/ja/learn/oci-cd3-greenfield/index.html#introduction)
[Youtube 学習コンテンツ](https://oracle-devrel.github.io/cd3-automation-toolkit/latest/learningvideos/)
[GitHubのCD3リポジトリ](https://github.com/oracle-devrel/cd3-automation-toolkit)