# アンシブル

BitwardenはAnsibleとの統合を提供し、シークレットマネージャーから秘密を取得し、それらをあなたのAnsibleプレイブックに注入することができます。ルックアッププラグインは、取得したシークレットをマスクされた環境変数としてAnsibleプレイブック内に注入します。コレクションを設定するには：

## 要件

- 私たちはPythonパッケージを[Python仮想環境](https://python.land/virtual-environments/virtualenv)にインストールすることをお勧めします。
- あなたのシステムにインストールされているAnsibleの現在のバージョン。
- [アクティブなサービス アカウント](https://bitwarden.com/ja-jp/help/secrets-manager-quick-start/#add-a-service-account/)を持つ Bitwarden Secrets Manager。

Ansibleコレクションを設定する前に、アクセストークンと設定に含めたいシークレットをアクセスするために、シークレットマネージャーも開くことをお勧めします。

## Bitwarden Ansible コレクションをインストールします

次のガイドは、Linuxマシンを使用したBitwardenコレクションのセットアップ例です。

1. Bitwarden SDKをインストールします：

```bash
pip install bitwarden-sdk
```
2. bitwarden.secretsコレクションをインストールします:

```bash
ansible-galaxy collection install bitwarden.secrets
```

Ansibleコレクションがインストールされたので、AnsibleプレイブックからBitwardenの秘密を呼び出すことができます。 `bitwarden.secrets.lookup`を使用します。次のセクションでは、このプロセスを示す例を含めます。

> [!NOTE] Mac OS ansible
> macOSのユーザーは、[Ansibleの上流の問題](https://docs.ansible.com/ansible/latest/reference_appendices/faq.html#running-on-macos-as-a-control-node)を避けるために、シェルで以下の環境変数を設定する必要があるかもしれません。
> 
> - `エクスポート OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES`

## Bitwardenの秘密を取得する

あなたのプレイブックからシークレットマネージャーからシークレットを取得するには、2つの方法があります：

### アクセストークンを環境変数として保存します。

シークレットマネージャーを使用して、シェルの環境変数としてアクセストークンを安全に設定し、プレイブックを使用して秘密を取得することができます。アクセス[トークンを認証する](https://bitwarden.com/ja-jp/help/developer-quick-start/#authenticate/)には：

1. シェルで、以下のコマンドを実行してアクセストークンの環境変数を設定します:

```bash
export BWS_ACCESS_TOKEN=<ACCESS_TOKEN_VALUE>
```
2. 環境変数が設定されたので、ルックアッププラグインを使用してプレイブックの変数を入力することができます。例えば：

```bash
vars:
 database_password: "{{ lookup('bitwarden.secrets.lookup', '<SECRET_ID>') }}"
```

> [!NOTE] Secure env variable in playbook
> 環境変数として`BWS_ACCESS_TOKEN`を設定することで、プレイブック内に生のアクセストークンの値を含めずにアクセストークンを参照することができます。

### プレイブックにアクセストークンを提供してください

シークレットマネージャーのアクセストークンは、プレイブック自体内で参照することもできます。この方法では、シェル内の`BWS_ACCESS_TOKEN`環境変数を使用する必要はありませんが、アクセストークンの値はプレイブック自体に保存されます。

1. アクセストークンは、次の例のようにプレイブックに含めることができます:

```bash
vars:
 password_with_a_different_access_token: "{{ lookup('bitwarden.secrets.lookup', '<SECRET_ID_VALUE>', 
access_token='<ACCESS_TOKEN_VALUE>') }}"
```

この方法を使用すると、複数のアクセストークンを単一のプレイブックで参照することができます。

## 異なるサーバーから秘密を取得する

Bitwarden自己ホスト型のユーザーは、`base_url,` `api_url` そして `identity_url`を含めることで、自分のBitwardenサーバーから秘密を取得することができます。

```bash
vars:
 secret_from_other_server: "{{ lookup('bitwarden.secrets.lookup', '<SECRET_ID>', base_url='https://bitwarden.example.com' ) }}"
 secret_advanced: >-
 {{ lookup('bitwarden.secrets.lookup', '<SECRET_ID>',
 api_url='https://bitwarden.example.com/api',
 identity_url='https://bitwarden.example.com/identity' ) }}
```

## 例のプレイブック

次は、いくつかの設定オプションを持つプレイブックファイルの例です。

```bash
---
- name: Using secrets from Bitwarden

 vars:
 bws_access_token: "{{ lookup('env', 'CUSTOM_ACCESS_TOKEN_VAR') }}"
 state_file_dir: "{{ '~/.config/bitwarden-sm' | expanduser }}"
 secret_id: "9165d7a8-2c22-476e-8add-b0d50162c5cc"

 secret: "{{ lookup('bitwarden.secrets.lookup', secret_id) }}"
 secret_with_field: "{{ lookup('bitwarden.secrets.lookup', secret_id, field='note' ) }}"
 secret_with_access_token: "{{ lookup('bitwarden.secrets.lookup', secret_id, access_token=bws_access_token ) }}"
 secret_with_state_file: "{{ lookup('bitwarden.secrets.lookup', secret_id, state_file_dir=state_file_dir ) }}"

 tasks:
 - name: Use the secret in a task
 include_tasks: tasks/add_db_user.yml # reference the secrets with "{{ secret }}", "{{ secret_with_field }}", etc.
```

> [!NOTE] Multiple CUSTOM_ACCESS_TOKEN
> 上記の例では、`CUSTOM_ACCESS_TOKEN_VAR `は、複数の異なるアクセストークンを含めることができることを示しています。これらはハードカード化する必要はなく、安全にあなたのプレイブックに供給することができます。

| 変数 | 追加情報 |
|------|------|
| `bws_access_token` | アクセストークン`env`変数を参照してください。 |
| `ステートファイルディレクトリ` | あなたの認証状態がキャッシュされるディレクトリ。 |
| `シークレットID` | あなたが検索したい秘密のID。 |
| `秘密` | 秘密の値を検索し、`"secret"`という名前の変数として保存します。 |
| `フィールド付きの秘密` | 追加フィールド出力を持つ秘密を検索します。この例では、検索は秘密の` 'メモ' `の値を返します。 |
| `アクセストークン付きの秘密` | リクエストに含まれるアクセストークンの値で秘密を検索します。 |
| `状態ファイル付きの秘密` | リクエストに含まれる事前に設定された状態ファイルを使用して秘密を検索します。 |

## 追加のリクエストとフィールド

`secret_id`に加えて、いくつかのフィールドを`bitwarden.secrets.lookup`に含めることができます。次のJSONオブジェクトには、プレイブックルックアップで参照できるすべてのフィールドが含まれています:

```bash
{
 "id": "be8e0ad8-d545-4017-a55a-b02f014d4158",
 "organizationId": "10e8cbfa-7bd2-4361-bd6f-b02e013f9c41",
 "projectId": "e325ea69-a3ab-4dff-836f-b02e013fe530",
 "key": "SES_KEY",
 "value": "0.982492bc-7f37-4475-9e60",
 "note": "",
 "creationDate": "2023-06-28T20:13:20.643567Z",
 "revisionDate": "2023-06-28T20:13:20.643567Z"
}
```

追加のフィールドを取得するために、たとえば`"メモ"`のようなものを、以下のコマンドをプレイブックに追加することができます：

```bash
vars:
 database_password: "{{ lookup('bitwarden.secrets.lookup', '0037ed90-efbb-4d59-a798-b103012487a0', field='note') }}"
```