<commit_before>packer-plugin-sakuracloud
===

![Test Status](https://github.com/sacloud/packer-plugin-sakuracloud/workflows/Tests/badge.svg)
[![Slack](https://img.shields.io/badge/Slack-Sacloud%20Workspace-brightgreen)](https://join.slack.com/t/sacloud/shared_invite/zt-k8ovnmqq-4V4gsZhOsBdCiLz9KaqRkA)
[![License](https://img.shields.io/github/license/sacloud/packer-plugin-sakuracloud)](LICENSE)
[![Version](https://img.shields.io/github/v/tag/sacloud/packer-plugin-sakuracloud)](https://github.com/sacloud/packer-plugin-sakuracloud/releases/latest)
![Downloads](https://img.shields.io/github/downloads/sacloud/packer-plugin-sakuracloud/total)

A plugin of packer for SAKURA Cloud / さくらのクラウド用Packerプラグイン

## 概要

`packer-plugin-sakuracloud`は[さくらのクラウド](http://cloud.sakura.ad.jp)での
アーカイブ(構築済みOSのテンプレート)を[Packer](https://packer.io)で作成するためのPackerプラグインです。

## 必要なもの

- `packer` v1.7+
- さくらのクラウド APIキー

> :warning: `packer-plugin-sakuracloud` v0.7以降では`packer` v1.7以降が必要となります。  
> 1.7以前の`packer`を利用したい場合はv0.7より古いバージョンをご利用ください。

## 実行方法

以下の何かの方法でプラグインをインストールして`packer`コマンドを実行します。

- `packer init`を利用(HCLテンプレートのみ)
- プラグインの手動インストール

### `packer init`を利用

HCLテンプレートでのみ利用可能です。  
テンプレートに以下のような`required_plugin`ブロックを記載し`packer init`でプラグインをインストールします。

```hcl
packer {
  required_plugins {
    sakuracloud = {
      version = ">= 0.7.0"
      source = "github.com/sacloud/sakuracloud"
    }
  }
}
```

### プラグインの手動インストール

[リリースページ](https://github.com/sacloud/packer-plugin-sakuracloud/releases/latest)から各プラットフォーム用のバイナリをダウンロードし、
以下のドキュメントに記載されている所定のディレクトリに配置します。

https://www.packer.io/docs/plugins

## Dockerでの実行

Dockerで実行する場合、以下のように実行します。

    docker run -it --rm ghcr.io/sacloud/packer:latest [packerサブコマンド] [packerオプション]

APIキーを環境変数で指定する場合、`-e`オプションなどを適切に指定して実行してください。

    # APIキーを環境変数で指定、カレントディレクトリのexample.jsonをテンプレートとして指定してビルドする例
    $ docker run -it --rm \
             -e SAKURACLOUD_ACCESS_TOKEN \
             -e SAKURACLOUD_ACCESS_TOKEN_SECRET \
             -v $PWD:/work \
             -w /work \
             ghcr.io/sacloud/packer:latest build example.pkr.hcl

> :bulb: `ghcr.io/sacloud/packer`にはプラグインが手動インストール済みです。このため`packer init`は不要です。  

### `homebrew`を利用する場合(macOSでHomebrewをご利用の場合)

v0.7以降`homebrew`はサポートされなくなりました。  
`packer init`、またはプラグインの手動インストールにてご利用ください。

## 使い方(アーカイブ作成)

#### APIキーの設定

APIキーを環境変数に設定しておきます。
(APIキーは以下で作成するjsonファイルに記載することも可能です)

    $ export SAKURACLOUD_ACCESS_TOKEN=[APIトークン]
    $ export SAKURACLOUD_ACCESS_TOKEN_SECRET=[APIシークレット]

#### テンプレートファイルの作成(HCL)

Packer 1.5以降で利用できるHCLテンプレートに対応しています。

> :bulb: JSONテンプレートを利用したい場合は次節`テンプレートファイルの作成(JSON)`を参照してください。

以下の様なファイルを作成し拡張子を`.pkr.hcl`とすることで`packer build`が実行できます。

```hcl
# Dockerから利用、またはプラグインの手動インストールを行う場合は以下のブロックをコメントアウトしてください。
packer {
  required_plugins {
    sakuracloud = {
      version = ">= 0.7.0"
      source = "github.com/sacloud/sakuracloud"
    }
  }
}

source "sakuracloud" "example" {
  zone = "is1b" # アーカイブを作成する対象ゾーン
  zones = ["is1a", "is1b", "tk1a", "tk1v"] # 作成したアーカイブを転送する宛先ゾーン

  os_type   = "centos7"
  password  = "<PASSWORD>"
  disk_size = 20
  disk_plan = "ssd"

  core        = 2
  memory_size = 4

  archive_name        = "packer-example-centos"
  archive_description = "description of archive"
}

build {
  sources = [
    "source.sakuracloud.example"
  ]
  provisioner "shell" {
    inline = [
      "yum update -y",
      "curl -fsSL https://get.docker.com/ | sh",
      "systemctl enable docker.service",
    ]
  }
}
```

#### テンプレートファイルの作成(JSON)

以下の例は石狩第2ゾーン(`is1b`)に、CentOSパブリックアーカイブをベースとしたアーカイブを作成します。
プロビジョニングとして、`shell`にてdockerのインストールを行なっています。

#### packer用jsonファイルの例
```sh
$ cat <<EOF > example.json
{
    "builders": [{
        "type": "sakuracloud",
        "zone": "is1b",
        "os_type": "centos7",
        "password": "<PASSWORD>"
    }],
    "provisioners":[
    {
        "type": "shell",
        "inline": [
            "yum update -y",
            "curl -fsSL https://get.docker.com/ | sh",
            "systemctl enable docker.service"
        ]
    }]
}
EOF
```

作成したら以下のように`packer build`を実行すると、さくらのクラウド上にアーカイブが作成されます。

    $ packer build example.json

さくらのクラウド上のパブリックアーカイブだけでなく、ISOイメージからの構築も可能です。
詳細は[テンプレートのサンプル](#テンプレートサンプル)を参照してください。



## オプション一覧

jsonファイルで指定できるオプションの一覧は以下の通りです。

### 必須項目

- `access_token`(string): APIトークン。この値は環境変数`SAKURACLOUD_ACCESS_TOKEN`で指定することも可能です。

- `access_token_secret`(string): APIシークレット。この値は環境変数`SAKURACLOUD_ACCESS_TOKEN_SECRET`で指定することも可能です。

- `zone`(string): 対象ゾーン。`tk1a`(東京)又は`is1b`(石狩第2)を指定

- `os_type`(string): ベースとするアーカイブの種別。以下の値が指定可能です。

| 値                              | 説明                                                    |
|--------------------------------|-------------------------------------------------------|
| `centos`                       | CentOS(最新安定板)                                         |
| `centos8`                      | CentOS 8                                              |
| `centos8stream`                | CentOS 8 Stream                                       |
| `centos7`                      | CentOS 7                                              |
| `centos6`                      | CentOS 6                                              |
| `ubuntu`                       | Ubuntu(最新安定板)                                         |
| `ubuntu2004`                   | Ubuntu 20.04                                          |
| `ubuntu1804`                   | Ubuntu 18.04                                          |
| `ubuntu1604`                   | Ubuntu 16.04                                          |<commit_msg>Update docs<commit_after>packer-plugin-sakuracloud
===

![Test Status](https://github.com/sacloud/packer-plugin-sakuracloud/workflows/Tests/badge.svg)
[![Slack](https://img.shields.io/badge/Slack-Sacloud%20Workspace-brightgreen)](https://join.slack.com/t/sacloud/shared_invite/zt-k8ovnmqq-4V4gsZhOsBdCiLz9KaqRkA)
[![License](https://img.shields.io/github/license/sacloud/packer-plugin-sakuracloud)](LICENSE)
[![Version](https://img.shields.io/github/v/tag/sacloud/packer-plugin-sakuracloud)](https://github.com/sacloud/packer-plugin-sakuracloud/releases/latest)
![Downloads](https://img.shields.io/github/downloads/sacloud/packer-plugin-sakuracloud/total)

A plugin of packer for SAKURA Cloud / さくらのクラウド用Packerプラグイン

## 概要

`packer-plugin-sakuracloud`は[さくらのクラウド](http://cloud.sakura.ad.jp)での
アーカイブ(構築済みOSのテンプレート)を[Packer](https://packer.io)で作成するためのPackerプラグインです。

## 必要なもの

- `packer` v1.7+
- さくらのクラウド APIキー

> :warning: `packer-plugin-sakuracloud` v0.7以降では`packer` v1.7以降が必要となります。  
> 1.7以前の`packer`を利用したい場合はv0.7より古いバージョンをご利用ください。

## 実行方法

以下の何かの方法でプラグインをインストールして`packer`コマンドを実行します。

- `packer init`を利用(HCLテンプレートのみ)
- プラグインの手動インストール

### `packer init`を利用

HCLテンプレートでのみ利用可能です。  
テンプレートに以下のような`required_plugin`ブロックを記載し`packer init`でプラグインをインストールします。

```hcl
packer {
  required_plugins {
    sakuracloud = {
      version = ">= 0.7.0"
      source = "github.com/sacloud/sakuracloud"
    }
  }
}
```

### プラグインの手動インストール

[リリースページ](https://github.com/sacloud/packer-plugin-sakuracloud/releases/latest)から各プラットフォーム用のバイナリをダウンロードし、
以下のドキュメントに記載されている所定のディレクトリに配置します。

https://www.packer.io/docs/plugins

## Dockerでの実行

Dockerで実行する場合、以下のように実行します。

    docker run -it --rm ghcr.io/sacloud/packer:latest [packerサブコマンド] [packerオプション]

APIキーを環境変数で指定する場合、`-e`オプションなどを適切に指定して実行してください。

    # APIキーを環境変数で指定、カレントディレクトリのexample.jsonをテンプレートとして指定してビルドする例
    $ docker run -it --rm \
             -e SAKURACLOUD_ACCESS_TOKEN \
             -e SAKURACLOUD_ACCESS_TOKEN_SECRET \
             -v $PWD:/work \
             -w /work \
             ghcr.io/sacloud/packer:latest build example.pkr.hcl

> :bulb: `ghcr.io/sacloud/packer`にはプラグインが手動インストール済みです。このため`packer init`は不要です。  

### `homebrew`を利用する場合(macOSでHomebrewをご利用の場合)

v0.7以降`homebrew`はサポートされなくなりました。  
`packer init`、またはプラグインの手動インストールにてご利用ください。

## 使い方(アーカイブ作成)

#### APIキーの設定

APIキーを環境変数に設定しておきます。
(APIキーは以下で作成するjsonファイルに記載することも可能です)

    $ export SAKURACLOUD_ACCESS_TOKEN=[APIトークン]
    $ export SAKURACLOUD_ACCESS_TOKEN_SECRET=[APIシークレット]

#### テンプレートファイルの作成(HCL)

Packer 1.5以降で利用できるHCLテンプレートに対応しています。

> :bulb: JSONテンプレートを利用したい場合は次節`テンプレートファイルの作成(JSON)`を参照してください。

以下の様なファイルを作成し拡張子を`.pkr.hcl`とすることで`packer build`が実行できます。

```hcl
# Dockerから利用、またはプラグインの手動インストールを行う場合は以下のブロックをコメントアウトしてください。
packer {
  required_plugins {
    sakuracloud = {
      version = ">= 0.7.0"
      source = "github.com/sacloud/sakuracloud"
    }
  }
}

source "sakuracloud" "example" {
  zone = "is1b" # アーカイブを作成する対象ゾーン
  zones = ["is1a", "is1b", "tk1a", "tk1v"] # 作成したアーカイブを転送する宛先ゾーン

  os_type   = "centos7"
  password  = "<PASSWORD>"
  disk_size = 20
  disk_plan = "ssd"

  core        = 2
  memory_size = 4

  archive_name        = "packer-example-centos"
  archive_description = "description of archive"
}

build {
  sources = [
    "source.sakuracloud.example"
  ]
  provisioner "shell" {
    inline = [
      "yum update -y",
      "curl -fsSL https://get.docker.com/ | sh",
      "systemctl enable docker.service",
    ]
  }
}
```

#### テンプレートファイルの作成(JSON)

以下の例は石狩第2ゾーン(`is1b`)に、CentOSパブリックアーカイブをベースとしたアーカイブを作成します。
プロビジョニングとして、`shell`にてdockerのインストールを行なっています。

#### packer用jsonファイルの例
```sh
$ cat <<EOF > example.json
{
    "builders": [{
        "type": "sakuracloud",
        "zone": "is1b",
        "os_type": "centos7",
        "password": "<PASSWORD>"
    }],
    "provisioners":[
    {
        "type": "shell",
        "inline": [
            "yum update -y",
            "curl -fsSL https://get.docker.com/ | sh",
            "systemctl enable docker.service"
        ]
    }]
}
EOF
```

作成したら以下のように`packer build`を実行すると、さくらのクラウド上にアーカイブが作成されます。

    $ packer build example.json

さくらのクラウド上のパブリックアーカイブだけでなく、ISOイメージからの構築も可能です。
詳細は[テンプレートのサンプル](#テンプレートサンプル)を参照してください。

## オプション一覧

jsonファイルで指定できるオプションの一覧は以下の通りです。

### 必須項目

- `access_token`(string): APIトークン。この値は環境変数`SAKURACLOUD_ACCESS_TOKEN`で指定することも可能です。

- `access_token_secret`(string): APIシークレット。この値は環境変数`SAKURACLOUD_ACCESS_TOKEN_SECRET`で指定することも可能です。

- `zone`(string): 対象ゾーン。以下の値が指定可能です。
  - `is1a`: 石狩第1ゾーン
  - `is1b`: 石狩第2ゾーン
  - `tk1a`: 東京第1ゾーン
  - `tk1b`: 東京第2ゾーン
    
- `os_type`(string): ベースとするアーカイブの種別。以下の値が指定可能です。

| 値                              | 説明                                                    |
|--------------------------------|-------------------------------------------------------|
| `centos`                       | CentOS(最新安定板)                                         |
| `centos8`                      | CentOS 8                                              |
| `centos8stream`                | CentOS 8 Stream                                       |
| `centos7`                      | CentOS 7                                              |
| `centos6`                      | CentOS 6                                              |
| `ubuntu`                       | Ubuntu(最新安定板)                                         |
| `ubuntu2004`                   | Ubuntu 20.04                                          |
| `ubuntu1804`                   | Ubuntu 18.04                                          |
| `ubuntu1604`                   | Ubuntu 16.04                                          |
{'fraction_non_alphanumeric': 0.14226655882088612, 'fraction_numerical': 0.013930079985620562, 'mean_word_length': 2.351807228915663, 'pattern_counts': {'":': 16, '<': 11, '<?xml version=': 0, '>': 21, 'https://': 24, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 36, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3646735', 'n_tokens_mistral': 5771, 'n_tokens_neox': 5346, 'n_words': 471}