API Connect v10 カタログ内のデータをToolkitでコピーしてみた ②

# はじめに

　以前、[こちらの記事](https://qiita.com/ryota_n/items/06bede3fb202a211bb9e)でToolkitを使用して、カタログの情報をコピーする方法を紹介しました。しかし、API定義やOAuth Provider定義をコピーする際に、前提となるリソースがある場合は、別途、追加手順が必要になりますので、その方法を紹介いたします。

今回は、以下のリソースを使用する前提で手順を紹介いたします。

- **API定義**
    - Invokeポリシー等でTLSプロファイル（暗号資材リソース）を参照
- **OAuthプロバイダー定義**
    - ユーザー・セキュリティーで認証URL（ユーザー・レジストリーリソース）を参照



また、API Connectで設定可能なこれらのリソースは、さらに別のリソースを参照していますので、そちらも考慮する必要があります。以下のような参照構造を理解したうえで、リソース情報のコピーが必要となります。また、これらのリソースは、一意なURLが割り当てられており、そのURLを参照しています。そのため、別の環境にコピーする際には、URLを更新する必要があります。

**リソース定義の参照構造**

- OAuthプロバイダー
    - ユーザー・レジストリー（認証URLタイプ）
- ユーザー・レジストリー（認証URLタイプ）
    - TLSクライアント・プロファイル
- 暗号資材
    - TLSクライアント・プロファイル
        - 鍵ストア


以下、各構造のリソースについて情報取得、登録の流れを説明していきます。
この記事では、API Connect v10.0.8.0をベースに検証しています。

# 1. 移行元の情報取得


Toolkitで情報を取得するため、プロバイダー組織にアクセス権のあるユーザーでAPI Managerにログインします。

```
#環境設定ファイルの作成

$ cat config.env
# API Manager認証設定
APIM_USER='test-admin'
APIM_PASSWORD='***'
APIM_SERVER='https://manager.example.com'
APIM_PROVIDER_REALM=provider/default-idp-2

# ターゲット環境設定
T_GWS='apigateway'
T_CATALOG='test-catalog'
T_PORG='test-org'

# 環境設定ファイルの読み込み
$ source ./config.env

# ログインコマンド
$ apic client-creds:set credentials.json
$ apic login --username ${APIM_USER} --password ${APIM_PASSWORD} --server ${APIM_SERVER} --realm ${APIM_PROVIDER_REALM}
example.com に正常にログインしました
```



## 1.1. 暗号素材リソースの取得

### 1.1.1. 鍵ストアリソース


以下のように`keystores:list`でプロバイダー組織内の鍵ストアのリストを取得し、`keystores:get`で対象のリソースを取得できます。

```
$ apic keystores:list --org ${T_PORG}  --server ${APIM_SERVER} 

$ apic keystores:get --org ${T_PORG}  --server ${APIM_SERVER} test-key
test-key   test-key.yaml   https://api.example.com/api/orgs/688efdd8-3738-41e1-8aa9-1c4ceb450e8f/keystores/4e507fc2-955e-41c0-892d-37dae9993a8c 
```

### 1.1.2. TLSプロファイルリソース

同様に`tls-client-profiles:list-all`でプロバイダー組織内のTLSプロファイルのリストを取得し、`tls-client-profiles:get`で対象のリソースを取得できます。

```
$ apic tls-client-profiles:list-all --org ${T_PORG}  --server ${APIM_SERVER}  

$ apic tls-client-profiles:get --org ${T_PORG}  --server ${APIM_SERVER}  tls-client-profile:1.0.0
tls-client-profile:1.0.0   tls-client-profile_1.0.0.yaml  https://api.example.com/api/orgs/688efdd8-3738-41e1-8aa9-1c4ceb450e8f/tls-client-profiles/82ff57ad-eb8d-4c38-8862-417b4b15def4
```

以下のように_urlというキーワードで検索すると、keystore_urlが指定されていることがわかります。
こちらは環境固有のURLであるため、移行先でリソースを登録する際にはURLが変わるため更新する必要があります。

```
# 参照リソースURLの確認
$ grep "_url" tls-client-profile_1.0.0.yaml
keystore_url: 'https://api.example.com/api/orgs/688efdd8-3738-41e1-8aa9-1c4ceb450e8f/keystores/4e507fc2-955e-41c0-892d-37dae9993a8c'
org_url: 'https://api.example.com/api/orgs/688efdd8-3738-41e1-8aa9-1c4ceb450e8f'
```


## 1.2. ユーザーレジストリーリソースの取得


同様にユーザーレジストリーも対象の情報を取得します。


```
$ apic user-registries:list --org ${T_PORG}  --server ${APIM_SERVER}

$ apic user-registries:get --org ${T_PORG}  --server ${APIM_SERVER} sampleauth
sampleauth   sampleauth.yaml   https://api.example.com/api/user-registries/688efdd8-3738-41e1-8aa9-1c4ceb450e8f/0b8ccecc-55eb-42d3-81d2-c8da9950e32e 
```

以下のように_urlsというキーワードで検索すると、2つの宛先が指定されていることがわかります。
これらも環境固有のURLであるため、移行先でリソースを登録する際にはURLが変わるため更新する必要があります。

```
# 参照リソースURLの確認
$ grep "_url" sampleauth.yaml
integration_url: 'https://api.example.com/api/cloud/integrations/user-registry/987e470c-07b2-4c87-bf0a-24bbd1fefa05'
tls_client_profile_url: 'https://api.example.com/api/orgs/688efdd8-3738-41e1-8aa9-1c4ceb450e8f/tls-client-profiles/82ff57ad-eb8d-4c38-8862-417b4b15def4'
org_url: 'https://api.example.com/api/orgs/688efdd8-3738-41e1-8aa9-1c4ceb450e8f'
```

### 1.2.1. Integration設定の確認

上記の`integration_url`については認証URLのテンプレートを指定する環境固有の宛先になります。
以下のコマンドで確認することができます。

```
$ apic integrations:list --subcollection user-registry  --server ${APIM_SERVER} | grep authurl

authurl    [state: enabled]   https://api.example.com/api/cloud/integrations/user-registry/987e470c-07b2-4c87-bf0a-24bbd1fefa05
```



## 1.3. OAuthプロバイダーリソースの取得

同様に`oauth-providers:list`で一覧を取得し、対象のOAuthプロバイダーリソースを`oauth-providers:get`で取得します。

```
$ apic oauth-providers:list --org ${T_PORG}  --server ${APIM_SERVER}  

$ apic oauth-providers:get --org ${T_PORG}  --server ${APIM_SERVER} test-oauth
test-oauth   test-oauth.yaml   https://api.example.com/api/orgs/688efdd8-3738-41e1-8aa9-1c4ceb450e8f/oauth-providers/47fdbc9e-a7f2-48c3-b62f-409495398714 
```

以下のように_urlsというキーワードで検索すると、user_registry_urlsと、tls_client_profile_urlsが参照されていることがわかります。これらは、環境固有のURLであるため、移行先でリソースを登録する際にはURLが変わるため更新する必要があります（これらの情報は別設定で有効になるため削除でOK）。

```
# 参照リソースURL設定の確認
$ grep -A1 "_url" test-oauth.yaml
user_registry_urls:
  - 'https://api.example.com/api/user-registries/688efdd8-3738-41e1-8aa9-1c4ceb450e8f/0b8ccecc-55eb-42d3-81d2-c8da9950e32e'
tls_client_profile_urls:
  - 'https://api.example.com/api/orgs/688efdd8-3738-41e1-8aa9-1c4ceb450e8f/tls-client-profiles/121c7c13-1b23-41b3-bb05-a4bf0d076f8f'
orgs/688efdd8-3738-41e1-8aa9-1c4ceb450e8f/oauth-providers/47fdbc9e-a7f2-48c3-b62f-409495398714 
```


## 1.4. 製品定義の取得

以下のように`products:list-all`でカタログ内の製品のリストを取得し、`products:get`で対象の製品/APIを取得できます。

```
# リストの表示
$ apic products:list-all --org ${T_PORG}  --server ${APIM_SERVER} --scope catalog --catalog {T_CATALOG}

# 対象の製品/APIの取得
$ apic products:get  --org ${T_PORG}  --server ${APIM_SERVER} --scope catalog --catalog {T_CATALOG} test-product:1.0.0 
test-api:1.0.0   test-api_1.0.0.yaml      
test-product:1.0.0   test-product_1.0.0.yaml
```

以下のようにtls-profileというキーワードで検索すると、API定義の中で参照していることがわかります。
ただし、この参照はリソース名だけのため、移行先で同じ名前のリソースが作られていれば修正の必要はありません。

```
# 参照TLSプロファイル有無の確認
$ grep "tls-profile"  test-api_1.0.0.yaml
test-api_1.0.0.yaml:        tls-profile: tls-client-profile:1.0.0
```


# 2. 移行先への情報登録

取得した情報をもとに、ソースファイルを編集して新規作成していきます。
移行先の環境情報に応じて、設定を変更します。

```
T_CATALOG='test-catalog-copy'
T_PORG='test-org-copy'
```

1.の手順で取得したyamlファイルを活用して、移行先で同じ定義を作成していきます。

## 2.1. 暗号素材の登録

### 2.1.1. 鍵ストア

鍵ストアファイルについては、中身を見てみるとわかりますが、秘密鍵情報が含まれないことがわかります。
これはAPI Connectの仕様で一度、インポートした秘密鍵情報はエクスポートできない制限によるものです。

そのため、移行元で使用していたpemファイル等を使用して、再度登録する必要があります。
以下のような形式で、keystoreフィールドにクライアント証明書と秘密鍵をPEM形式で追記します。

```
$ cat test-key.yaml
type: 'keystore'
name: 'test-key'
title: 'test-key'
keystore: |
  -----BEGIN CERTIFICATE-----
  MIID***
  -----END CERTIFICATE-----
  -----BEGIN PRIVATE KEY-----
  MIIE***
  -----END PRIVATE KEY-----
```

このファイルを使用して、以下のようなコマンドで新規作成が可能となります。
新しい環境でのkeystoreのURLが同時に確認できます。

```
$ apic keystores:create --org ${T_PORG} --server ${APIM_SERVER} test-key.yaml

test-key   https://api.example.com/api/orgs/ca8375e9-b361-4e89-8de5-7e0cd9891d64/keystores/59f58842-7390-4006-8f0d-95554022f3ff
```

### 2.1.2. TLSプロファイル

1.1.2で取得したtls-client-profile_1.0.0.yamlファイルを使用しますが、`keystore_url`を2.1.1.で取得したURLに修正します。
そのほか不要な情報が含まれていた場合は削除します（`id`、`org_url`など残っていても無視される値もあります）。`owned`については削除しないとエラーとなるため削除します。


- **削除項目**
    - owned
- **修正項目**
    - keystore_url

以下のようなコマンドで新規作成ができ、新しい環境でのTLSプロファイルのURLが同時に確認できます。

```
$ apic tls-client-profiles:create --org ${T_PORG}  --server ${APIM_SERVER}  tls-client-profile_1.0.0.yaml
tls-client-profile:1.0.0   https://api.example.com/api/orgs/ca8375e9-b361-4e89-8de5-7e0cd9891d64/tls-client-profiles/1930d633-fb1f-4af7-aa81-3b7b80f05711
```

## 2.2. ユーザーレジストリーリソースの登録

1.2.で取得していたsampleauth.yamlファイルを使用しますが、`tls_client_profile_url`を2.1.2.で取得したURLに修正します。
また、`integration_url`は1.2.1.と同様に取得した値に修正します。
そのほか不要な情報が含まれていた場合は削除します（`id`、`org_url`など残っていても無視される値もあります）。`owned`については削除しないとエラーとなるため削除します。


- **削除項目**
    - owned
- **修正項目**
    - integration_url
    - tls_client_profile_url

以下のようなコマンドで新規作成ができ、新しい環境でのユーザーレジストリーのURLが同時に確認できます。

```
$ apic user-registries:create --org ${T_PORG}  --server ${APIM_SERVER}  sampleauth.yaml
sampleauth   https://api.example.com/api/user-registries/ca8375e9-b361-4e89-8de5-7e0cd9891d64/9d69d77d-3dd0-42c1-bc8e-1801dcec5285
```

## 2.3. OAuthプロバイダーリソースの登録

1.3.で取得していたtest-oauth.yamlファイルを使用しますが、`user_registry_urls`、`tls_client_profile_url`は削除します。
そのほか不要な情報が含まれていた場合は削除します（`id`、`org_url`など残っていても無視される値もあります）。`owned`と`x-ibm-name`については削除しないとエラーとなるため削除します。

- **削除項目**
    - owned
    - x-ibm-name
    - user_registry_urls
    - tls_client_profile_urls


```
$ apic oauth-providers:create --org ${T_PORG}  --server ${APIM_SERVER}  test-oauth.yaml
test-oauth   https://api.example.com/api/orgs/ca8375e9-b361-4e89-8de5-7e0cd9891d64/oauth-providers/a6ac1b60-f936-44d6-9904-d490f26ca8f0
```


## 2.4. 製品定義の登録

### 2.4.1. カタログの紐づけ作業

以上でリソースの登録は完了しました。
次に先ほど登録したTLSプロファイルと、OAuthプロバイダーはカタログで使用するために紐づける必要があります。

#### ① TLSプロファイル構成

2.1.2で取得したURLをもとに、以下のような形式で定義ファイルを作成します。

```
$ cat configured-tls.yaml
tls_client_profile_url: 'https://api.example.com/api/orgs/ca8375e9-b361-4e89-8de5-7e0cd9891d64/tls-client-profiles/1930d633-fb1f-4af7-aa81-3b7b80f05711'
```

以下のコマンドで構成できます。

```
$ apic configured-tls-client-profiles:create --scope catalog --org ${T_PORG}  --server ${APIM_SERVER}  --catalog ${T_CATALOG} configured-tls.yaml
tls_client_profile_url: 'https://api.example.com/api/orgs/ca8375e9-b361-4e89-8de5-7e0cd9891d64/tls-client-profiles/1930d633-fb1f-4af7-aa81-3b7b80f05711'
```

#### ② OAuthプロバイダー構成

同様に2.3.で取得したURLをもとに、以下のような形式で定義ファイルを作成します。

```
$ cat configured-oauth.yaml
oauth_provider_url: 'https://api.example.com/api/orgs/ca8375e9-b361-4e89-8de5-7e0cd9891d64/oauth-providers/a6ac1b60-f936-44d6-9904-d490f26ca8f0'

```

以下のコマンドで構成できます。

```
$ apic configured-oauth-providers:create --scope catalog --org ${T_PORG}  --server ${APIM_SERVER}  --catalog ${T_CATALOG} configured-oauth.yaml
oauth_provider_url: 'https://api.example.com/api/orgs/ca8375e9-b361-4e89-8de5-7e0cd9891d64/oauth-providers/a6ac1b60-f936-44d6-9904-d490f26ca8f0'
***
```

### 2.4.2 製品の公開

以上でリソースの準備が整いました。
API定義ではリソース名のみの参照になりますので、特に変更は不要になります。
1.4.で取得した製品定義を使用して、公開して問題がないことを確認します。

```
$ apic products:publish  --org ${T_PORG}  --server ${APIM_SERVER} --scope catalog --catalog ${T_CATALOG} test-product_1.0.0.yaml
test-product:1.0.0    [state: published]   https://api.example.com/api/catalogs/ca8375e9-b361-4e89-8de5-7e0cd9891d64/47a95489-37d8-4c08-8570-56f2ff61ed2e/products/b12dda60-4cb3-43a4-bfc3-338a1189fb0a

```

以上です。