ACI の Annotation とは

Cisco ACI には Annotation という機能があります。 今回は Annotation 機能の概要についてメモしておきます。

Annotation とは

Annotation は「注釈」なだけであり、ACI の機能には影響しません。 つまり、「Annotation を設定したのでパフォーマンスが向上する」「通信が制御される」ということは ありません。 Annotation は主に以下のような用途で利用します。 AWS の Tags と似た性質を持っています。

  • 設定は任意である (必要無ければ設定しなくても問題無い)
  • 様々な設定に付与することが出来る
  • ひとつの設定に対して複数の Annotation を設定することが出来る
  • 単なる説明書き (≒ Description) として利用出来る
  • スクリプトや MSO や Terraform、Ansible などのオーケストレーターから ACI の機能を呼び出す際の目印 (マーカー) として利用出来る

Annotation 機能の変遷

6.0 系の公式マニュアルですが Annotations には下記のように記載されています。 これを見ると「Annotation という機能が ACI バージョンの進化と共に、どのように変遷してきたのか」ということが分かります。

You can add arbitrary key:value pairs of metadata to an object as annotations (tagAnnotation). Annotations are provided for the user's custom purposes, such as descriptions, markers for personal scripting or API calls, or flags for monitoring tools or orchestration applications such as Cisco Multi-Site Orchestrator (MSO). Because APIC ignores these annotations and merely stores them with other object data, there are no format or content restrictions imposed by APIC.

Evolution of Annotations

APIC support for user-defined annotation information has changed over time in the following steps:

  • Prior to Cisco APIC Release 4.2(4), APIC supported tag instances (tagInst), which stored a simple string. In APIC GUI menus, these were labeled as "Tags."
  • In Cisco APIC Release 4.2(4), because many modern systems use a key and value pair as a label, changes were made to move to key:value annotations (tagAnnotation) as the main label option for API. The shortcut API to query objects via tag instances (/api/tag/your_tag.json ) was deprecated. The APIC GUI continued to use the simple string tag instances (tagInst), labeled as "Tags.".
  • In Cisco APIC Release 5.1(1), tag instances (tagInst) were deprecated in the GUI. GUI menus still used the term "Tags," but actually configured annotations (tagAnnotation). Also beginning with this release, a list of all annotations can be viewed from Fabric > Fabric policies > Tags.
  • In Cisco APIC release 5.2(1), GUI menu labels were changed from "Tags" to "Annotations." This change was made to avoid confusion with Policy Tags.

Annotation の設定画面

Tenant の場合、Annotation の設定箇所は以下です。


(6.0 系の場合) + マークをクリックすると、以下のように Key / Value の形で Annotation を設定します。


前述の通り、Annotation は複数、設定することが出来ます。 複数設定した場合は以下のように表示されます。


Annotation を含む XML 例

以下の Key & Value ペアを設定する場合を考えます。

Key Value
orchestrator terraform

この Annotation を設定した Tenant の XML 例は以下の通りです。

<?xml version="1.0" encoding="UTF-8"?>
<imdata totalCount="1">
  <fvTenant annotation="orchestrator:terraform" descr="" dn="uni/tn-Tenant1" name="Tenant1" nameAlias="" ownerKey="" ownerTag="" userdom=":all:">
    <vnsSvcCont annotation="" userdom="all"/>
    <fvRsTenantMonPol annotation="" tnMonEPGPolName="" userdom="all"/>
    <fvEpTags annotation="" userdom="all"/>

特殊な Key「orchestrator」について

以下の Annotation を持つ Tenant を設定してみます。

  1. orchestrator:ansible
  2. other:Other1
  3. orchestrator:sample
  4. orchestrator:terraform

これらは Tenant 一覧 (All Tenants) では以下のように表示されます。



  • orchestrator Key を持つ場合、特殊な表示がされる
  • orchestrator Key に ansibleterraform という値を設定した場合、先頭が大文字になる
  • orchestrator Key に sample といった値を設定した場合、先頭は小文字のまま

以下は Tenant の設定を見ていきます。


Annotation に orchestrator:ansible が設定されている Tenant の場合、以下のように表示されます。 画面上部には This object was created from the Ansible orchestrator. It is recommended to only make changes from the Ansible orchestrator. と表示され、Tenant 自体にも Ansible のアイコンが表示されています。



Annotation に orchestrator:terraform が設定されている Tenant の場合、以下のように表示されます。 Ansible の場合と同様、画面上部には This object was created from the Terraform orchestrator. It is recommended to only make changes from the Terraform orchestrator. と表示され、Tenant 自体にも Terraform のアイコンが表示されています。


尚、Terraform から設定した場合は自動的に、設定したすべての対象に orchestrator:terraform という Annotation が設定されます。


Annotation に orchestrator:sample が設定されている Tenant の場合、以下のように表示されます。 この場合は画面上部に This object is managed by an unknown orchestrator. It is recommended to only make changes from the appropriate orchestrator. と表示され、「不明なオーケストレータ」として認識されていることが分かります。