ゴーゲッター
1.7.6
go-getter は、主な入力形式として URL を使用して、さまざまなソースからファイルまたはディレクトリをダウンロードするための Go (golang) 用のライブラリです。
このライブラリの利点は、単一の文字列を入力として使用して、さまざまなソース (ファイル パス、Git、HTTP、Mercurial など) からダウンロードできる柔軟性です。これにより、実装者はさまざまなソースからダウンロードする方法を知るという負担が軽減されます。
ディテクタの概念により、無効な URL が自動的に適切な URL に変換されます。たとえば、「github.com/bashicorp/go-getter」は Git URL に変わります。または、「./foo」はファイル URL になります。これらは拡張可能です。
このライブラリは、Terraform ではモジュールのダウンロードに使用され、Nomad ではバイナリのダウンロードに使用されます。
パッケージのドキュメントは GoDoc にあります。
インストールは通常のgo getで実行できます。
$ go get github.com/hashicorp/go-getter
go-getter には、URL 文字列をテストするために使用できるコマンドもあります。
$ go install github.com/hashicorp/go-getter/cmd/go-getter ... $ go-getter github.com/foo/bar ./foo ...
このコマンドは、URL 構造を検証するのに役立ちます。
ユーザーが指定した URL からリソースを取得することは本質的に危険な操作であり、アプリケーションがサーバー側のリクエスト フォージェリ、パス トラバーサル、サービス拒否、またはその他のセキュリティ上の欠陥に対して脆弱になる可能性があります。
go-getter には、これらのセキュリティ問題の一部に対する軽減策が含まれていますが、セキュリティが重要な状況では依然として注意して使用する必要があります。これらのリスクの一部を軽減するために構成できる利用可能なセキュリティ オプションを確認してください。
go-getter は、機密データを含む可能性のある呼び出し元提供のクエリ パラメーターを含む値を返す場合があります。どのパラメータが機密であるか、どのパラメータが機密ではないかに関するコンテキストは、go-getter の呼び出し元のみが知り、各ユースケースに固有です。呼び出し元には、機密データがログに残らないように、ゴーゲッターの戻り値 (エラー メッセージなど) が適切に処理およびサニタイズされていることを確認することをお勧めします。
go-getter は、単一文字列 URL を入力として使用し、さまざまなプロトコルからダウンロードします。 gogetter は、この URL を使って特定のことを行うためのさまざまな「トリック」を備えています。このセクションでは URL 形式について説明します。
プロトコルは、特定のメカニズムを使用してファイル/ディレクトリをダウンロードするために使用されます。プロトコルの例としては、Git や HTTP があります。
検出機能は、有効または無効な URL が特定のパターンに一致する場合に、その URL を別の URL に変換するために使用されます。例: 「github.com/user/repo」は、完全に有効な Git URL に自動的に変換されます。これにより、go-getter は非常にユーザーフレンドリーになります。
go-getter はすぐに使用できる次のプロトコルをサポートします。 Getterインターフェイスを実装することで、実行時に追加のプロトコルを拡張できます。
ローカルファイル
Git
マーキュリアル
HTTP
アマゾンS3
Google GCP
上記のプロトコルに加えて、go-getter には「検出器」と呼ばれるものがあります。これらは URL を取得し、その URL に最適なプロトコルを自動的に選択しようとします。これには、プロトコルの変更も必要になる場合があります。次の検出がデフォルトで組み込まれています。
「./foo」などのファイルパスは自動的に絶対ファイルURLに変更されます。
「github.com/mitchellh/vagrant」などの GitHub URL は、HTTP 経由で Git プロトコルに自動的に変更されます。
「gitlab.com/inkscape/inkscape」などの GitLab URL は、HTTP 経由で Git プロトコルに自動的に変更されます。
「bitbucket.org/mitchellh/vagrant」などの BitBucket URL は、BitBucket API を使用して Git または mercurial プロトコルに自動的に変更されます。
ソース URL によっては、使用するプロトコルがあいまいな場合があります。たとえば、「http://github.com/mitchellh/vagrant.git」は、HTTP URL または Git URL を参照できます。この URL の曖昧さをなくすために、強制プロトコル構文が使用されます。
プロトコルの強制は、URL の先頭にプロトコルを付け、その後に二重コロンを付けることで実行できます。例: git::http://github.com/mitchellh/vagrant.git Git プロトコルを使用して指定された HTTP URL をダウンロードします。
強制プロトコルは検出器もオーバーライドします。
強制的なプロトコルがない場合は、URL 上で検出器が実行され、とにかくプロトコルを変換する可能性があります。上記の例では、Git 検出器が GitHub URL であることを検出したため、どちらの方法でも Git プロトコルを使用したことになります。
各プロトコルは、そのプロトコルを構成するためのプロトコル固有のオプションをサポートできます。たとえば、 gitプロトコルは、その Git リポジトリに対してチェックアウトする参照を指示するrefクエリ パラメーターの指定をサポートしています。
オプションは、go-getter に指定される URL (または URL に似た文字列) のクエリ パラメーターとして指定されます。上記の Git の例を使用すると、以下の URL は go-getter への有効な入力となります。
github.com/hashicorp/go-getter?ref=abcd1234
プロトコル固有のオプションは、URL 形式セクションの下に記載されています。ただし、これらは URL の一部であるため、存在することがわかるようにここで指摘します。
ダウンロードしたディレクトリから特定のサブディレクトリのみをダウンロードする場合は、二重スラッシュ//の後にサブディレクトリを指定できます。 go-getter はまず、二重スラッシュの前に指定された URL を (二重スラッシュを指定しなかったかのように) ダウンロードしますが、その後、二重スラッシュの後のパスをターゲット ディレクトリにコピーします。
たとえば、この GitHub リポジトリをダウンロードしているが、 testdataディレクトリのみをダウンロードしたい場合は、次の操作を行うことができます。
https://github.com/hashicorp/go-getter.git//testdata
これを/tmpディレクトリにダウンロードした場合、ファイル/tmp/archive.gzが存在します。このファイルはこのリポジトリのtestdataディレクトリにありますが、サブディレクトリを指定したため、go-getter はそのディレクトリの内容のみを自動的にコピーしたことに注意してください。
サブディレクトリ パスでは、ファイルシステムのグロブ パターンを使用することもできます。パスは1 つのエントリと正確に一致する必要があります。そうでない場合、ゴーゲッターはエラーを返します。これは、正確なディレクトリ名はわからないが、予測可能な名前付け構造に従っている場合に便利です。
たとえば、次の URL も機能します。
https://github.com/hashicorp/go-getter.git//test-*
あらゆるプロトコルのファイルをダウンロードする場合、go-getter はチェックサムを自動的に検証します。チェックサムはファイルのダウンロードにのみ機能し、ディレクトリには機能しませんが、チェックサムはどのプロトコルでも機能することに注意してください。
ファイルをチェックサムするには、 checksumクエリ パラメータを URL に追加します。 go-getter は、このクエリ パラメーターを自動的に解析し、それを使用してチェックサムを検証します。パラメーター値は、 type:valueまたは単にvalueの形式にすることができます。ここで、 type は "md5"、"sha1"、"sha256"、"sha512" または "file" です。 「値」は、「ファイル」の実際のチェックサム値またはダウンロード URL である必要があります。 type部分を省略した場合、チェックサム文字列の長さに基づいて型が推測されます。例:
./foo.txt?checksum=md5:b7d96c89d09d9e204f5fedc4d5d55b21
./foo.txt?checksum=b7d96c89d09d9e204f5fedc4d5d55b21
./foo.txt?checksum=file:./foo.txt.sha256sum
ファイルからチェックサムを取得する場合 (例: checksum=file:urlの場合)、go-getter は同じ設定を使用してfile:の後の URL にリンクされているファイルを取得します。たとえば、 file:http://releases.ubuntu.com/cosmic/MD5SUMSでは、go-getter は http プロトコルを使用して、前述の URL にチェックサム ファイルをダウンロードします。 go-getter がサポートするすべてのプロトコルを使用できます。チェックサム ファイルは一時ファイルにダウンロードされ、解析されます。一時ファイルの保存先は、システム固有の環境変数を設定することで変更できます。UNIX の場合はTMPDIR 。 Windows ではTMP 、 TEMP 、またはUSERPROFILE 。一時ディレクトリの選択の詳細については、os.TempDir の godoc を参照してください。ファイルの内容は BSD または GNU スタイルであることが期待されます。チェックサム ファイルの処理が完了したら、それは削除されます。
チェックサム クエリ パラメーターがバックエンド プロトコル実装に送信されることはありません。 go-getter 自体によってより高いレベルで使用されます。
宛先ファイルが存在し、チェックサムが一致する場合: ダウンロードはスキップされます。
go-getter は、要求されたファイルの拡張子に基づいて (任意のプロトコル上で) ファイルまたはディレクトリにファイルを自動的に解凍します。これは、ファイルとディレクトリの両方のダウンロードで機能します。
go-getter は、アーカイブの形式を指定するarchiveクエリ パラメーターを探します。これが指定されていない場合、go-getter はパスの拡張子を使用して、アーカイブされているかどうかを確認します。アーカイブ解除は、 archiveクエリ パラメータをfalseに設定することで明示的に無効にできます。
次のアーカイブ形式がサポートされています。
tar.gzとtgz
tar.bz2およびtbz2
tar.xzとtxz
zip
gz
bz2
xz
たとえば、URL の例を以下に示します。
./foo.zip
これは自動的に ZIP ファイルであると推測され、解凍されます。アーカイブの種類を明示的に指定することもできます。
./some/other/path?archive=zip
最後に、アーカイブを完全に無効にすることができます。
./some/path?archive=false
アーカイブ解除を、チェックサムなどの優れた機能の他の機能と組み合わせることができます。特別なarchiveクエリ パラメーターは、最終的なプロトコル ダウンローダーに進む前に URL から削除されます。
このセクションでは、go-getter に指定できるプロトコル固有のオプションについて説明します。これらのオプションは、通常のクエリ パラメーターとして入力に追加する必要があります (ただし、HTTP ヘッダーは例外です)。 go-getter の使用状況に応じて、アプリケーションはオプションを入力する別の方法を提供する場合があります。たとえば、Nomad は、URL ではなくオプションを指定するための優れたオプション ブロックを提供します。
以下のオプションはすべてのプロトコルで使用できます。
archive - このファイルのアーカイブを解除するために使用するアーカイブ形式、またはアーカイブ解除を無効にする場合は "" (空の文字列)。詳細については、上記のアーカイブ サポートに関する完全なセクションを参照してください。
checksum - ダウンロードされたファイルまたはアーカイブを検証するためのチェックサム。形式と詳細については、上記のチェックサムに関するセクション全体を参照してください。
filename - ファイル ダウンロード モードの場合、ディスク上にダウンロードされたファイルの名前を指定できます。ディレクトリモードでは効果がありません。
file )なし
git ) ref - チェックアウトする Git 参照。これは ref なので、コミット SHA、ブランチ名などを指すことができます。ブランチ名などの名前付き ref の場合、go-getter は取得するたびにそれを最新に更新します。
sshkey - クローン作成時に使用する SSH 秘密キー。指定されたキーは、base64 でエンコードされた文字列である必要があります。たとえば、ディスク上の秘密キー ファイルから適切なsshkey生成するには、 base64 -w0 を実行します。
注: この機能を使用するには、Git 2.3 以降が必要です。
depth - Git クローンの深さ。指定された数値は、リポジトリからクローンを作成する最後のnリビジョンを指定します。
git getter は、 git::ssh://[email protected]/foo/barのような URL スタイルの SSH アドレスと、 git::[email protected]/foo/barのような "scp スタイル" アドレスの両方を受け入れます。後者の場合、ユーザー名の接頭辞が正確にgit@であれば、 git:: force 接頭辞を省略することができます。
「scp スタイル」アドレスをssh://スキーム プレフィックスと組み合わせて使用することはできません。その場合、コロンはホストからのパスを区切るのではなく、接続するオプションのポート番号をマークするために使用されるからです。
hg ) rev - チェックアウトする Mercurial リビジョン。
http )go-getter で HTTP 基本認証を使用するには、 https://Aladdin:[email protected]/index.htmlのように、URL 内のホスト名の前にusername:password@を追加するだけです。ユーザー名とパスワードを含むすべての特殊文字は URL エンコードする必要があります。
オプションのリクエスト ヘッダーは、カスタムHttpGetterで指定することで追加できます (他のほとんどのオプションのようにクエリ パラメーターとしてではありません)。これらのヘッダーは、問題のゲッターが行うすべてのリクエストで送信されます。
s3 )S3 は、URL でさまざまなアクセス設定を取得します。標準の AWS 環境変数が設定されている場合は、これらの変数も読み取ることに注意してください。 Minio などの S3 準拠サーバーもサポートされています。クエリパラメータが存在する場合は、それらが優先されます。
aws_access_key_id - AWS アクセスキー。
aws_access_key_secret - AWS アクセスキーのシークレット。
aws_access_token - AWS アクセス トークン (使用されている場合)。
aws_profile - ローカル ~/.aws/ config からこのプロファイルを使用します。他の 3 つよりも優先されます。
go-getter を使用していて、認証情報の使用を避けるために EC2 IAM インスタンス プロファイルを使用したい場合は、これらを省略するだけで、プロファイルが利用可能な場合は自動的に使用されます。
Minio サポートに go-gitter を使用する場合は、次の点を考慮する必要があります。
aws_access_key_id (必須) - Minio アクセスキー。
aws_access_key_secret (必須) - Minio アクセスキーのシークレット。
region (オプション - デフォルトは us-east-1) - 使用するリージョン識別子。
version (オプション - デフォルトは Minio のデフォルト) - 構成ファイルの形式。
S3 には、バケットを参照するために使用されるいくつかのアドレス指定スキームがあります。これらはここにリストされています: https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-bucket-intro.html
これらのアドレス指定スキームの例をいくつか示します。
s3::https://s3.amazonaws.com/bucket/foo
s3::https://s3-eu-west-1.amazonaws.com/bucket/foo
バケット.s3.amazonaws.com/foo
bucket.s3-eu-west-1.amazonaws.com/foo/bar
「s3::http://127.0.0.1:9000/test-bucket/hello.txt?aws_access_key_id=KEYID&aws_access_key_secret=SECRETKEY®ion=us-east-2」
gcs )GCS にアクセスするには、認証資格情報を提供する必要があります。詳細については、こちらをご覧ください
gcs::https://www.googleapis.com/storage/v1/bucket
gcs::https://www.googleapis.com/storage/v1/bucket/foo.zip
www.googleapis.com/storage/v1/bucket/foo
get_gcs.goのテストでは、環境に GCP 認証情報が設定されている必要があります。 これらの資格情報は、任意のプロジェクトに対する任意のレベルの権限を持つことができ、存在するだけで十分です。 これは、 GOOGLE_APPLICATION_CREDENTIALS="~/path/to/credentials.json"またはGOOGLE_CREDENTIALS="{stringified-credentials-json}"を設定することを意味します。 この構成により、CircleCI の外部コントリビューターに対してget_gcs_test.goが失敗します。
シンボリックリンクを無効にする
ゲッター クライアントの構成では、シンボリック リンク (ディレクトリの外部を指している可能性がある) への書き込みやコピーを防止するDisableSymlinksオプションを使用することをお勧めします。
client := getter.Client{ // これにより、シンボリックリンクを介したファイルのコピーまたは書き込みが防止されます DisableSymlinks: true,
} X-Terraform-Get無効化または制限する
Go-Getter は、 X-Terraform-Getヘッダーを介した任意のリダイレクトをサポートします。この機能は、Terraform のユースケースをサポートするために存在しますが、ほとんどのアプリケーションでは必要ない可能性があります。
HttpGetter使用するコードの場合、次の構成オプションを追加します。
var httpGetter = &getter.HttpGetter{ // ほとんどのクライアントは X-Terraform-Get を無効にする必要があります // 以下の注を参照 XTerraformGetDisabled: true, // あなたのソフトウェアはおそらく X-Terraform-Get に依存していませんが、 // 依存している場合、上記のフィールドを false に設定し、さらに // 無限のリダイレクトを防ぐために XTerraformGet Limit を設定する必要があります // XTerraformGetLimit: 10,}タイムアウトを強制する
HttpGetter 、タイムアウトやその他のリソースを制約する構成オプションをサポートしています。 GitGetterとHgGetterタイムアウトのみをサポートします。
HttpGetterの構成:
var httpGetter = &getter.HttpGetter{ // プリフェッチ HEAD リクエストを無効にする DoNotCheckHeadFirst: true,
// 上記の設定の代わりに、 // HEAD リクエストに適切なタイムアウトを設定できます。 // HeadFirstTimeout: 10 * time.Second, // HTTP 操作の読み取りタイムアウト ReadTimeout: 30 * time.Second, // // ゲッターによって読み取れる最大バイト数 MaxBytes: 500000000, // 500 MB} GitGetterまたはHgGetter使用するコードの場合は、 Timeoutオプションを設定します。
var gitGetter = &getter.GitGetter{ // git 操作に適切なタイムアウトを設定します。 タイムアウト: 5 * time.Minute,
} var hgGetter = &getter.HgGetter{ // hg 操作に適切なタイムアウトを設定します。 タイムアウト: 5 * time.Minute,
} 
