Snowflake Native App インストールガイド
#######################################

概要
***********************

このガイドでは、Snowflake Native Appをインストールする手順を説明します。
Snowflake Native Appにより、Snowflake環境内でAPC-CLIの機能をGUI操作で利用できます。

前提条件
***********************

- Dockerがインストールされていること
- Snowflakeアカウントへのアクセス権限があること
- ACCOUNTADMIN権限を持つユーザーアカウントがあること

インストール手順
***********************

.. note::

    ステップ1、2はSnowflakeのSQLワークシートで実行してください。
    ステップ3以降はローカル環境のターミナルで実行してください。

1. デプロイ用ロールの作成（Snowflakeコンソール）
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. important::
    このステップはACCOUNTADMIN権限を持ったユーザーが実行する必要があります。

**1.1 デプロイ用ロールの作成**

デプロイ用ロールを作成します。

.. code-block:: sql

    CREATE ROLE autoprivacy_deploy_role;

**1.2 ユーザーへのロール付与**

作成したロールをユーザーに付与します。

.. code-block:: sql

    GRANT ROLE autoprivacy_deploy_role TO USER <your_username>;

**1.3 必要な権限の付与**

Native Appのインストールに必要な権限を付与します。

.. code-block:: sql

    GRANT CREATE INTEGRATION ON ACCOUNT TO ROLE autoprivacy_deploy_role;
    GRANT CREATE WAREHOUSE ON ACCOUNT TO ROLE autoprivacy_deploy_role WITH GRANT OPTION;
    GRANT CREATE DATABASE ON ACCOUNT TO ROLE autoprivacy_deploy_role;
    GRANT CREATE APPLICATION PACKAGE ON ACCOUNT TO ROLE autoprivacy_deploy_role;
    GRANT CREATE APPLICATION ON ACCOUNT TO ROLE autoprivacy_deploy_role;
    GRANT CREATE COMPUTE POOL ON ACCOUNT TO ROLE autoprivacy_deploy_role WITH GRANT OPTION;

2. 必要なオブジェクトの作成（Snowflakeコンソール）
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**2.1 ロールの切り替え**

デプロイ用ロールに切り替えます。

.. code-block:: sql

    USE ROLE autoprivacy_deploy_role;

**2.2 イメージリポジトリの作成**

このNativeAppではSnowpark Container Serviceを使用しているため、Dockerイメージを格納するためのイメージリポジトリが必要です。

以下のコマンドでイメージリポジトリを作成します。

.. code-block:: sql

    CREATE DATABASE autoprivacy_img_database;
    CREATE SCHEMA img_schema;
    CREATE IMAGE REPOSITORY img_repo;

3. Snowflake CLIの設定（ローカルターミナル）
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Snowflake CLIは、Native AppのデプロイやDockerイメージの認証を行うために必要です。

.. important::

    以降のステップはターミナルで実行してください。

**3.1 Snowflake CLIのインストール**

Snowflake CLIのインストール方法については、`Snowflake公式ドキュメント <https://docs.snowflake.com/developer-guide/snowflake-cli/installation/installation>`_ を参照してください。

**3.2 コネクションの作成**

Snowflake CLIでコネクションを作成します。

.. code-block:: bash

    snow connection add

以下の情報を入力してください：

- **コネクション名**: ``autoprivacy_snowflake_connection``
- **role**: ``autoprivacy_deploy_role``
- **database**: ``autoprivacy_img_database``
- **schema**: ``img_schema``

その他の値は、お使いのSnowflakeアカウントに応じて設定してください。

**3.3 コネクションの確認**

作成したコネクションが正常に動作するかテストします。

.. code-block:: bash

    snow connection test -c autoprivacy_snowflake_connection

以下のような結果が表示されれば、成功です。

.. code-block:: bash

    +----------------------------------------------------------------------------------+
    | key             | value                                                          |
    |-----------------+----------------------------------------------------------------|
    | Connection name | autoprivacy_snowflake_connection                               |
    | Status          | OK                                                             |
    | Host            | <USER_ACCOUNT>.snowflakecomputing.com                          |
    | Account         | <USER_ACCOUNT>                                                 |
    | User            | <USER_NAME>                                                    |
    | Role            | AUTOPRIVACY_DEPLOY_ROLE                                        |
    | Database        | AUTOPRIVACY_IMG_DATABASE                                       |
    | Warehouse       | <WAREHOUSE_NAME>                                               |
    +----------------------------------------------------------------------------------+

4. Dockerイメージの準備とアップロード（ローカルターミナル）
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**4.1 イメージリポジトリURLの取得**

SnowflakeのイメージリポジトリのURLを取得します。

.. code-block:: bash

    REPO_URL=$(snow spcs image-repository url autoprivacy_img_database.img_schema.img_repo -c autoprivacy_snowflake_connection)
    echo $REPO_URL

**4.2 APCイメージの取得**

.. note::
    利用可能なDockerイメージのバージョンは、`GitHub Container Registry <https://github.com/acompany-develop/dcr-docs-examples/pkgs/container/dcr-docs-examples%2Fapc_image>`_ で確認し、適切なバージョンを指定してください。

.. code-block:: bash

    docker pull ghcr.io/acompany-develop/dcr-docs-examples/apc_image:<version>

**4.3 イメージのタグ付け**

取得したイメージにSnowflakeリポジトリ用のタグを付けます。

.. code-block:: bash

    docker tag ghcr.io/acompany-develop/dcr-docs-examples/apc_image:<version> $REPO_URL/apc_image:latest

**4.4 Snowflakeレジストリへの認証**

Snowflakeのコンテナレジストリにログインします。

.. code-block:: bash

    snow spcs image-registry login -c autoprivacy_snowflake_connection

**4.5 イメージのアップロード**

DockerイメージをSnowflakeにアップロードします。

.. code-block:: bash

    docker push $REPO_URL/apc_image:latest

5. Native Appソースコードの準備（ローカルターミナル）
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**ソースコードのダウンロード**

`こちら <https://github.com/acompany-develop/dcr-docs-examples/releases>`_ から適切なバージョンを選択し、Assetsから ``snowflake_native_app.zip`` をダウンロードし、ローカルに展開してください。

6. プロジェクト定義ファイルの作成（ローカルターミナル）
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

以下の値を任意の値に設定した上で、``snowflake_native_app`` ディレクトリと同じ階層に ``snowflake.yml`` として作成します：

- ``<app_name>``: アプリケーション名
- ``<warehouse_name>``: 任意のwarehouse名をご指定ください

.. code-block:: yaml

    definition_version: 2
    entities:
      autoprivacy_native_app_pkg:
        type: application package
        manifest: snowflake_native_app/manifest.yml
        artifacts:
          - src: snowflake_native_app/*
            dest: ./
        meta:
          role: autoprivacy_deploy_role
          warehouse: <warehouse_name>
      <app_name>:
        type: application
        from:
          target: autoprivacy_native_app_pkg
        debug: false
        meta:
          role: autoprivacy_deploy_role
          warehouse: <warehouse_name>

**ディレクトリ構成**

作成後は以下のようなディレクトリ構成になります：

.. code-block:: bash

    .
    ├── snowflake.yml
    └── snowflake_native_app
        ├── manifest.yml
        ├── readme.md
        ├── setup.sql
        └── streamlit
            ├── environment.yml
            └── streamlit_app.py

7. デプロイとインストール（ローカルターミナル）
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**7.1 アプリケーションのデプロイ**

以下のコマンドでアプリケーションをデプロイします：

.. code-block:: bash

    snow app run -c autoprivacy_snowflake_connection

**7.2 インストール完了**

デプロイが完了すると、``<app_name>`` で指定した名前でアプリケーションがインストールされます。

.. tip::
    プロジェクト定義ファイルのapp_nameを変更して、再度デプロイすることで、別の名前で同じアプリケーションを複数インストールすることができます。