設定 Apigee mTLS

Edge for Private Cloud 4.19.01

在叢集中的每個節點上安裝 apigee-mtls 元件後，您必須設定並初始化該元件。方法是產生憑證/金鑰組，並在管理機器上更新設定檔。接著，您可以將產生的相同檔案部署至叢集中的所有節點，並初始化本機 apigee-mtls 元件。

設定 apigee-mtls (初次安裝後)

本節說明如何在初次安裝後立即為單一資料中心設定 Apigee mTLS。如要瞭解如何更新現有的 Apigee mTLS 安裝作業，請參閱「變更現有的 apigee-mtls 設定」。如要瞭解如何設定多個資料中心，請參閱「為 Apigee mTLS 設定多個資料中心」。

以下是設定 apigee-mtls 的一般程序：

  1. 更新設定檔：在管理機器上更新設定檔，以納入 apigee-mtls 設定。
  2. 安裝 Consul 並產生憑證：安裝 Consul，並使用該工具產生 TLS 憑證 (僅限一次)。

    此外，請編輯 Apigee mTLS 設定檔，以便：

    1. 新增憑證資訊
    2. 定義叢集的拓撲

    請注意，您可以使用現有的憑證，也可以透過 Consul 產生憑證。

  3. 發布設定檔和憑證：將相同的產生憑證/金鑰組合和更新的設定檔，發布至叢集中的所有節點。
  4. 初始化 apigee-mtls：初始化每個節點上的 apigee-mtls 元件。

我們會在後續章節中說明每個步驟。

步驟 1：更新設定檔

本節說明如何修改設定檔，納入 mTLS 設定屬性。如要進一步瞭解設定檔的一般資訊，請參閱「建立設定檔」。

將設定檔更新為含有 mTLS 相關屬性後，請將其複製到叢集中的所有節點，然後再初始化這些節點上的 apigee-mtls 元件。

參照設定檔的指令會使用「config_file」表示其位置會因您在各個節點上儲存的位置而有所不同。

如何更新設定檔：

  1. 在管理機器上開啟設定檔。
  2. 複製下列 mTLS 設定屬性組合，並貼到設定檔中： 
    ALL_IP="ALL_PRIVATE_IPS_IN_CLUSTER"
ZK_MTLS_HOSTS="ZOOKEEPER_PRIVATE_IPS"
CASS_MTLS_HOSTS="CASSANDRA_PRIVATE_IPS"
PG_MTLS_HOSTS="POSTGRES_PRIVATE_IPS"
RT_MTLS_HOSTS="ROUTER_PRIVATE_IPS"
MS_MTLS_HOSTS="MGMT_SERVER_PRIVATE_IPS"
MP_MTLS_HOSTS="MESSAGE_PROCESSOR_PRIVATE_IPS"
QP_MTLS_HOSTS="QPID_PRIVATE_IPS"
LDAP_MTLS_HOSTS="OPENLDAP_PRIVATE_IPS"
MTLS_ENCAPSULATE_LDAP="y"

ENABLE_SIDECAR_PROXY="y"
ENCRYPT_DATA="BASE64_GOSSIP_MESSAGE"
PATH_TO_CA_CERT="PATH/TO/consul-agent-ca.pem"
PATH_TO_CA_KEY="PATH/TO/consul-agent-ca-key.pem"
APIGEE_MTLS_NUM_DAYS_CERT_VALID_FOR="NUMBER_OF_DAYS"

    根據您的設定，設定每個屬性的值。

    下表說明這些設定屬性：

    屬性 說明
    ALL_IP 以空格分隔的清單，列出叢集中所有節點的私人主機 IP 位址。

    IP 位址的順序不重要，但叢集中的所有設定檔中必須使用相同的順序。

    如果您為多個資料中心設定 Apigee mTLS，請列出所有區域中所有主機的所有 IP 位址。
    LDAP_MTLS_HOSTS 叢集中 OpenLDAP 節點的私人主機 IP 位址。
    ZK_MTLS_HOSTS

    以空格分隔的私人主機 IP 位址清單，叢集中的 ZooKeeper 節點會託管在這些主機上。

    請注意，根據規定，ZooKeeper 節點至少必須有三個。
    CASS_MTLS_HOSTS 以空格分隔的私人主機 IP 位址清單，叢集中的 Cassandra 伺服器會在此主機上代管。
    PG_MTLS_HOSTS 以空格分隔的私人主機 IP 位址清單，這些主機會在叢集中代管 Postgres 伺服器。
    RT_MTLS_HOSTS 以空格分隔的私人主機 IP 位址清單，其中 Router 會在叢集中託管。
    MTLS_ENCAPSULATE_LDAP 會加密訊息處理器與 LDAP 伺服器之間的 LDAP 流量。設為 y。
    MS_MTLS_HOSTS 以空格分隔的私人主機 IP 位址清單，管理伺服器節點會在叢集中代管這些 IP 位址。
    MP_MTLS_HOSTS 以空格分隔的私人主機 IP 位址清單，叢集中的訊息處理器會託管在這些主機上。
    QP_MTLS_HOSTS 以空格分隔的私人主機 IP 位址清單，Qpid 伺服器會在叢集中託管這些 IP 位址。
    ENABLE_SIDECAR_PROXY 判斷 Cassandra 和 Postgres 是否應瞭解服務中介。

    您必須將此值設為「y」。
    ENCRYPT_DATA Consul 使用的 Base64 編碼加密金鑰。您是在步驟 2：安裝 Consul 並產生憑證中使用 consul keygen 指令產生這個金鑰。

    這個值必須在叢集中的所有節點上保持一致。
    PATH_TO_CA_CERT 節點上的憑證檔案位置。您是在步驟 2：安裝 Consul 並產生憑證中產生這個檔案。

    叢集中的所有節點都應使用相同的位置，以便設定檔一致。

    憑證必須採用 X509v3 編碼。
    PATH_TO_CA_KEY 節點上的金鑰檔案位置。您是在步驟 2：安裝 Consul 並產生憑證中產生這個檔案。

    叢集中的所有節點都應使用相同的位置，以便設定檔一致。

    金鑰檔案必須採用 X509v3 編碼。
    APIGEE_MTLS_NUM_DAYS_CERT_VALID_FOR

    產生自訂憑證時，憑證的有效天數。

    預設值為 365。最大值為 7865 天 (5 年)。

    除了上述屬性之外，在多資料中心設定中安裝 Apigee mTLS 時，還會使用其他幾個屬性。詳情請參閱「設定多個資料中心」。

  3. 請確認 ENABLE_SIDECAR_PROXY 屬性為「y」。
  4. 更新主機相關屬性中的 IP 位址。請務必使用私人 IP 位址參照各個節點，而非公開 IP 位址。

    在後續步驟中，您將設定其他屬性的值，例如 ENCRYPT_DATA、PATH_TO_CA_CERT 和 PATH_TO_CA_KEY。您尚未設定這些值。

    編輯 apigee-mtls 設定屬性時，請注意下列事項：

    • 所有屬性都是字串，您必須將所有屬性的值包在單引號或雙引號中。
    • 如果主機相關值有多個私人 IP 位址，請以空格分隔各個 IP 位址。
    • 在設定檔中，請為所有主機相關的屬性使用私人 IP 位址，而非主機名稱或公開 IP 位址。
    • 屬性值中的 IP 位址順序，必須與叢集中所有設定檔中的順序相同。
  5. 將變更儲存至設定檔。

步驟 2：安裝 Consul 並產生憑證

本節說明如何安裝 Consul 並產生憑證。

您必須選擇下列其中一種方法來產生憑證：

  • 使用 Consul 建立自己的 CA，如本節所述 (建議做法)
  • 使用現有 CA 的憑證搭配 Apigee mTLS (進階)

關於憑證

憑證包含下列項目：

  • 憑證：每個節點代管的 TLS 憑證
  • 金鑰：每個節點代管的 TLS 公開金鑰
  • Gossip 訊息：Base-64 編碼的加密金鑰

您只需為每個檔案產生單一版本。您將金鑰和憑證檔案複製到叢集中的所有節點，並將加密金鑰新增至設定檔，然後將設定檔複製到所有節點。

如要進一步瞭解 Consul 的加密實作方式，請參閱下列資源：

安裝 Consul 並產生憑證

您可以使用本機 Consul 二進位檔產生 Apigee mTLS 用於驗證私有雲叢集節點間安全通訊的憑證。因此，您必須先在管理機器上安裝 Consul，才能產生憑證。

如何安裝 Consul 並產生 mTLS 憑證：

  1. 在管理電腦上，從 HashiCorp 網站下載 Consul 1.6.2 二進位檔。
  2. 將下載的封存檔案內容解壓縮。例如，將內容擷取至 /opt/consul/。
  3. 在管理機器上，執行下列指令建立新的憑證授權單位 (CA)： 
    /opt/consul/consul tls ca create

    Consul 會建立下列檔案，也就是憑證/金鑰組：

    • consul-agent-ca.pem (憑證)
    • consul-agent-ca-key.pem (鍵)

    根據預設，憑證和金鑰檔案會採用 X509v3 編碼。

    稍後，您會將這些檔案複製到叢集中的所有節點。不過，您目前只能決定要將這些檔案放置在節點的哪裡。應位於每個節點的相同位置。例如 /opt/apigee/。

  4. 在設定檔中，將 PATH_TO_CA_CERT 的值設為要複製節點上 consul-agent-ca.pem 檔案的位置。例如： 
    PATH_TO_CA_CERT="/opt/apigee/consul-agent-ca.pem"
  5. 將 PATH_TO_CA_KEY 的值設為要複製節點上 consul-agent-ca-key.pem 檔案的位置。例如： 
    PATH_TO_CA_KEY="/opt/apigee/consul-agent-ca-key.pem"
  6. 執行下列指令，為 Consul 建立加密金鑰： 
    /opt/consul/consul keygen

    Consul 會輸出類似以下的隨機字串：

    QbhgD+EXAMPLE+Y9u0742X/IqX3X429/x1cIQ+JsQvY=
  7. 複製字串，並將其設為設定檔中 ENCRYPT_DATA 屬性的值。例如： 
    ENCRYPT_DATA="QbhgD+EXAMPLE+Y9u0742X/IqX3X429/x1cIQ+JsQvY="
  8. 儲存設定檔。

以下範例顯示設定檔中的 mTLS 相關設定 (以及示例值)：

...
IP1=10.126.0.121
IP2=10.126.0.124
IP3=10.126.0.125
IP4=10.126.0.127
IP5=10.126.0.130
ALL_IP="$IP1 $IP2 $IP3 $IP4 $IP5"
LDAP_MTLS_HOSTS="$IP3"
ZK_MTLS_HOSTS="$IP3 $IP4 $IP5"
CASS_MTLS_HOSTS="$IP3 $IP4 $IP5"
PG_MTLS_HOSTS="$IP2 $IP1"
RT_MTLS_HOSTS="$IP4 $IP5"
MS_MTLS_HOSTS="$IP3"
MP_MTLS_HOSTS="$IP4 $IP5"
QP_MTLS_HOSTS="$IP2 $IP1"
ENABLE_SIDECAR_PROXY="y"
ENCRYPT_DATA="QbhgD+EXAMPLE+Y9u0742X/IqX3X429/x1cIQ+JsQvY="
PATH_TO_CA_CERT="/opt/apigee/consul-agent-ca.pem"
PATH_TO_CA_KEY="/opt/apigee/consul-agent-ca-key.pem"
...

步驟 3：發布設定檔和憑證

使用 scp 等工具，將下列檔案複製到執行 ZooKeeper 的節點：

  • 設定檔：複製這個檔案的更新版本，並取代所有節點 (不只是執行 ZooKeeper 的節點) 上的現有版本。
  • consul-agent-ca.pem:複製至您在設定檔中指定為 PATH_TO_CA_CERT 值的位置。
  • consul-agent-ca-key.pem:複製至您在設定檔中指定為 PATH_TO_CA_KEY 值的位置。

請確認您複製憑證和金鑰檔案的位置，與步驟 2：安裝 Consul 並產生憑證中設定檔案的值相符。

步驟 4：初始化 apigee-mtls

更新設定檔、將設定檔和憑證複製到叢集中的所有節點，並在每個節點上安裝 apigee-mtls 後，您就可以在每個節點上初始化 apigee-mtls 元件。

如要初始化 apigee-mtls：

  1. 以超級使用者身分登入叢集中的節點。您可以按照任何順序，在節點上執行這些步驟。
  2. 將 apigee:apigee 使用者設為更新版設定檔的擁有者，如以下範例所示： 
    chown apigee:apigee config_file
  3. 執行下列指令，設定 apigee-mtls 元件： 
    /opt/apigee/apigee-service/bin/apigee-service apigee-mtls setup -f config_file
  4. (選用) 執行下列指令，確認設定是否成功： 
    /opt/apigee/apigee-mtls/lib/actions/iptables.sh validate
  5. 執行下列指令啟動 Apigee mTLS： 
    /opt/apigee/apigee-service/bin/apigee-service apigee-mtls start

    安裝 Apigee mTLS 後，您必須在節點上的任何其他元件「之前」啟動此元件。

  6. (僅限 Cassandra 節點) Cassandra 需要額外引數才能在安全性網格中運作。因此，您必須在每個 Cassandra 節點上執行下列指令： 
    /opt/apigee/apigee-service/bin/apigee-service apigee-cassandra setup -f config_file
/opt/apigee/apigee-service/bin/apigee-service apigee-cassandra configure
/opt/apigee/apigee-service/bin/apigee-service apigee-cassandra restart
  7. (僅限 Postgres 節點) Postgres 需要額外引數才能在安全網格中運作。因此，您必須在 Postgres 節點上執行下列操作：

    (僅限主版本)

    1. 在 Postgres 主節點上執行下列指令： 
      /opt/apigee/apigee-service/bin/apigee-service apigee-postgresql setup -f config_file
/opt/apigee/apigee-service/bin/apigee-service apigee-postgresql configure
/opt/apigee/apigee-service/bin/apigee-service apigee-postgresql restart

    (僅限待機)

    1. 備份現有的 Postgres 資料。如要安裝 Apigee mTLS，您必須重新初始化主/備用節點，因此會發生資料遺失的情形。詳情請參閱「為 Postgres 設定主/備援複寫」。
    2. 刪除所有 Postgres 資料： 
      rm -rf /opt/apigee/data/apigee-postgresql/pgdata
    3. 設定 Postgres，然後重新啟動 Postgres，如以下範例所示： 
      /opt/apigee/apigee-service/bin/apigee-service apigee-postgresql setup -f config_file
/opt/apigee/apigee-service/bin/apigee-service apigee-postgresql configure
/opt/apigee/apigee-service/bin/apigee-service apigee-postgresql restart

    如果您是在多資料中心拓樸上進行安裝，請為設定檔使用絕對路徑。

  8. 依啟動順序啟動節點上的其他 Apigee 元件，如以下範例所示： 
    /opt/apigee/apigee-service/bin/apigee-service component_name start
  9. 針對叢集中的每個節點重複執行這項程序。
  10. (選用) 使用下列一或多種方法，驗證 apigee-mtls 初始化是否成功：
    1. 驗證 iptables 設定
    2. 驗證遠端 Proxy 狀態
    3. 確認仲裁狀態

    如要瞭解這些方法，請參閱「驗證設定」。

變更現有的 apigee-mtls 設定

如要自訂現有的 apigee-mtls 設定，您必須解除安裝並重新安裝 apigee-mtls。

在此重申，變更現有的 Apigee mTLS 設定時：

  • 如果您變更設定檔，必須先解除安裝 apigee-mtls，然後重新執行 setup 或 configure： 
    # DO THIS:
/opt/apigee/apigee-service/bin/apigee-service apigee-mtls uninstall

# BEFORE YOU DO THIS:
/opt/apigee/apigee-service/bin/apigee-service apigee-mtls setup -f file
OR
/opt/apigee/apigee-service/bin/apigee-service apigee-mtls configure
  • 您必須在叢集中的所有節點上卸載並重新執行 setup 或 configure，而非只在單一節點上執行。