How to get started with modules - Resource Orchestration Service

Vous pouvez utiliser un module dans un autre module ou dans un modèle. Découvrez comment configurer les versions, les propriétés, les conditions et les dépendances des modules.

Prérequis

Si vous souhaitez utiliser un module personnalisé, assurez-vous qu'il est enregistré dans le compte cible. Pour plus d'informations, consultez les rubriques Créer un module personnalisé et Afficher un module personnalisé.
Vous pouvez utiliser directement les modules publics prêts à l'emploi fournis par Resource Orchestration Service (ROS). Pour plus d'informations, consultez la rubrique Afficher un module public.

Spécifier les configurations d'un module

Pour utiliser un module, traitez-le comme une ressource et effectuez les opérations suivantes :

Incluez le module dans la section Resources de votre modèle ou de votre module.
Spécifiez une version pour le module.
Spécifiez les configurations requises pour le module.

Spécifier une version pour un module

Spécifiez une version pour un module à l'aide du paramètre Version. Les valeurs valides pour Version sont les suivantes :

Valeur personnalisée : il s'agit de la version personnalisée du module, au format v+Nombre. Exemples : v1 et v10.

Lorsque vous utilisez un module public, nous vous recommandons de spécifier une valeur personnalisée pour Version.
default : la version par défaut du module.

Si vous ne supprimez pas le module, la version par défaut reste disponible.

Vous pouvez définir la version par défaut d'un module personnalisé en appelant une opération API ROS ou via la console ROS. Pour plus d'informations, consultez les rubriques SetResourceType et Modifier la version par défaut d'un module.

Lorsque vous utilisez un module personnalisé, nous vous recommandons de définir Version sur default.
latest : la dernière version du module.

Si vous ne supprimez pas le module, la dernière version reste disponible.

La dernière version du module change lorsque vous créez une nouvelle version ou que vous supprimez la version actuelle identifiée comme la plus récente.

Lors du développement ou du débogage d'un module, nous vous recommandons de définir Version sur latest.

Spécifier une propriété pour un module

Les paramètres de module permettent de transmettre des valeurs personnalisées depuis le modèle ou le module conteneur vers le module cible. Le module utilise ces valeurs pour configurer les propriétés de ses ressources ou de ses modules enfants. Si un paramètre de module n'est pas spécifié, la valeur définie par Default est utilisée.

Spécifier une propriété de module à l'aide d'un paramètre de modèle

Vous pouvez spécifier des valeurs personnalisées pour les paramètres du modèle et les utiliser pour configurer les propriétés d'un module. Pour plus d'informations sur la définition des paramètres de modèle, consultez la rubrique Paramètres.

L'exemple suivant utilise un modèle contenant la ressource MODULE::My::VPC::SampleVpc et le paramètre de modèle VpcName. Le paramètre de modèle VpcName spécifie la propriété VpcName dans le module.

ROSTemplateFormatVersion: '2015-09-01'
Parameters:
  VpcName:
    Description: Name for your sample vpc
    Type: String
Resources:
  MyVpc:
    Type: MODULE::My::VPC::SampleVpc
    Version: default
    Properties:
      VpcName:
        Ref: VpcName

Spécifier les propriétés d'un module enfant depuis le module parent

Si un module parent et son module enfant partagent le même paramètre, vous pouvez spécifier la valeur de ce paramètre pour le module enfant depuis le module parent.

Dans cet exemple, MODULE::My::VPC::SampleVpcPrivate est utilisé comme module enfant. Dans ce module, les paramètres VpcName et CidrBlock sont spécifiés pour configurer les propriétés VpcName et CidrBlock de la ressource ALIYUN::ECS::VPC. Le code ci-dessous illustre le module enfant :

ROSTemplateFormatVersion: '2015-09-01'
Description: A sample vpc.
Parameters:
  VpcName:
    Description: Name for the vpc
    Type: String
  CidrBlock:
    Description: Cidr block for the vpc
    Type: String
Resources:
  Vpc:
    Type: ALIYUN::ECS::VPC
    Properties:
      VpcName:
        Ref: VpcName
      CidrBlock:
        Ref: CidrBlock

Le module MODULE::My::VPC::SampleVpcPrivate est imbriqué dans le module MODULE::My::VPC::SampleVpc. Les configurations suivantes spécifient les paramètres du module enfant dans le module parent. Le code ci-dessous illustre le module parent.

Le paramètre CidrBlock du module enfant MODULE::My::VPC::SampleVpcPrivate est défini sur 192.168.0.0/16.
Un paramètre de module est défini pour le paramètre VpcName. Cela vous permet de spécifier le nom du VPC dans un modèle ou un module qui contient le module MODULE::My::VPC::SampleVpc.

ROSTemplateFormatVersion: '2015-09-01'
Description: A sample vpc.
Parameters:
  VpcName:
    Description: Name for the vpc
    Type: String
Resources:
  MyVpc:
    Type: MODULE::My::VPC::SampleVpcPrivate
    Version: default
    Properties:
      VpcName:
        Ref: VpcName
      CidrBlock: 192.168.0.0/16

Spécifier des contraintes pour un paramètre de module

Les paramètres de module ne prennent pas en charge l'application directe de contraintes. Pour appliquer des contraintes à un paramètre de module, créez un paramètre de modèle avec les contraintes souhaitées et référencez-le dans votre paramètre de module.

Spécifier une condition pour un module

Les conditions de module suivent la même syntaxe que les conditions de ressource. Les conditions d'un module sont transmises à toutes les ressources et à tous les modules enfants qu'il contient. Pour plus d'informations sur la définition des conditions, consultez la rubrique Conditions.

Spécifier une dépendance pour un module

Les dépendances de module suivent la même syntaxe que les dépendances de ressource. Les dépendances d'un module sont transmises à toutes les ressources et à tous les modules enfants qu'il contient. Pour plus d'informations sur la définition des dépendances, consultez la rubrique DependsOn.

Spécifier une politique de suppression pour un module

Les politiques de suppression de module suivent la même syntaxe que les politiques de suppression de ressource. La politique de suppression d'un module est héritée par toutes les ressources et tous les modules enfants qui ne possèdent pas leur propre politique de suppression. Pour plus d'informations sur la définition des politiques de suppression, consultez la rubrique DeletionPolicy.

Référencer les configurations d'un module

Référencer des ressources dans un module

Utilisez des noms logiques qualifiés complets pour référencer des ressources dans un module. Un nom logique qualifié complet se compose des éléments suivants :

Élément 1 : le nom logique spécifié pour le module dans le modèle ou le module qui le contient.
Élément 2 : le nom logique spécifié pour la ressource dans le module.

Vous pouvez séparer les éléments d'un nom logique qualifié complet par des points (.). Exemples : ModuleLogicalName.ResourceLogicalName et ParentModuleLogicalName.ChildModuleLogicalName.ResourceLogicalName.

Vous pouvez ensuite utiliser les fonctions intégrées Fn::GetAtt, Ref et Fn::Sub pour accéder aux ressources de la section Resources d'un module ou aux valeurs de propriété d'une ressource de module. Pour plus d'informations, consultez la rubrique Ressources.

// Fn::GetAtt example
GetAtt Example1:
  Fn::GetAtt:
    - ModuleLogicalName.ResourceLogicalName
    - AttributeName
GetAtt Example2:
  Fn::GetAtt:
    - ModuleLogicalName.ChildModuleLogicalName.ResourceLogicalName
    - AttributeName

// Ref example
Ref Example1:
  Ref: ModuleLogicalName.ResourceLogicalName
Ref Example2:
  Ref: ModuleLogicalName.ChildModuleLogicalName.ResourceLogicalName

// Fn::Sub example
Sub Example1:
  Fn::Sub: "${ModuleLogicalName.ResourceLogicalName}"
Sub Example2:
  Fn::Sub: "${ModuleLogicalName.ResourceLogicalName.AttributeName}"
Sub Example3:
  Fn::Sub: "${ModuleLogicalName.ChildModuleLogicalName.ResourceLogicalName}"
Sub Example4:
  Fn::Sub: "${ModuleLogicalName.ChildModuleLogicalName.ResourceLogicalName.AttributeName}"

Dans cet exemple, les configurations suivantes sont ajoutées :

Un modèle référence une propriété d'une ressource de module comme propriété d'une ressource dans le modèle lui-même.
Un modèle référence une sortie d'une ressource de module comme sortie dans le modèle lui-même.

La ressource ALIYUN::ECS::VPC dont le nom logique est Vpc est contenue dans le module MODULE::My::VPC::SampleVpc. Pour utiliser la fonction intégrée Ref afin de référencer l'ID de la ressource et la fonction intégrée Fn::GetAtt afin de référencer la sortie de la ressource, vous devez combiner le nom logique du module dans le modèle avec le nom logique de la ressource dans le module pour obtenir le nom logique qualifié complet de la ressource. Dans cet exemple, MyVpc est combiné avec Vpc pour obtenir MyVpc.Vpc.

Remarque

Pour obtenir le nom logique d'une ressource dans un module, vous pouvez afficher le module dans la console ROS. Pour plus d'informations, consultez les rubriques Afficher un module personnalisé et Afficher un module public.

Parameters:
  VpcName:
    Description: Name for your sample vpc
    Type: String
Resources:
  MyVpc:
    Type: MODULE::My::VPC::SampleVpc
    Version: default
    Properties:
      VpcName:
        Ref: VpcName
  MyVsw:
    Type: ALIYUN::ECS::VSwitch
    Properties:
      VpcId:
        Ref: MyVpc.Vpc
      CidrBlock: 192.168.1.0/24
      ZoneId:
        Fn::Select:
          - '0'
          - Fn::GetAZs:
              Ref: ALIYUN::Region
      VSwitchName: sample_vsw
Outputs:
  VpcId:
    Value:
      Fn::GetAtt:
        - MyVpc.Vpc
        - VpcId

Référencer des sorties dans un module

Traitez un module comme une ressource et ses sorties comme des propriétés de ressource. Utilisez les fonctions intégrées Fn::GetAtt et Fn::Sub pour accéder aux sorties du module. Pour plus d'informations, consultez la rubrique Sorties.

// Fn::GetAtt example
GetAtt Example1:
  Fn::GetAtt:
    - ModuleLogicalName
    - OutputName
GetAtt Example2:
  Fn::GetAtt:
    - ModuleLogicalName.ChildModuleLogicalName
    - OutputName

// Fn::Sub example
Sub Example1:
  Fn::Sub: "${ModuleLogicalName.OutputName}"
Sub Example2:
  Fn::Sub: "${ModuleLogicalName.ChildModuleLogicalName.OutputName}"

Référencer des conditions dans un module

Traitez un module comme un namespace pour obtenir son nom qualifié complet, et utilisez les fonctions intégrées Fn::If, Fn::Or, Fn::And et Fn::Not pour accéder aux conditions dans le module. Pour plus d'informations, consultez la rubrique Conditions.

// Fn::If example
If Example1:
  Fn::If:
    - ModuleLogicalName.ConditionName
    - Value for true
    - Value for false
If Example2:
  Fn::If:
    - ModuleLogicalName.ChildModuleLogicalName.ConditionName
    - Value for true
    - Value for false

// Fn::Or example
Or Example:
  Fn::Or:
    - ModuleLogicalName.ConditionName
    - ModuleLogicalName.ChildModuleLogicalName.ConditionName

// Fn::And example
And Example:
  Fn::And:
    - ModuleLogicalName.ConditionName
    - ModuleLogicalName.ChildModuleLogicalName.ConditionName

// Fn::Not example
Not Example1:
  Fn::Not: ModuleLogicalName.ConditionName
Not Example2:
  Fn::Not: ModuleLogicalName.ChildModuleLogicalName.ConditionName

Référencer des mappages dans un module

Traitez un module comme un namespace pour obtenir son nom qualifié complet, et utilisez la fonction intégrée Fn::FindInMap pour accéder aux mappages dans le module. Pour plus d'informations, consultez la rubrique Mappages.

// Fn::FindInMap example
FindInMap Example1:
  Fn::FindInMap:
    - ModuleLogicalName.MappingName
    - Key
    - SubKey
FindInMap Example2:
  Fn::FindInMap:
    - ModuleLogicalName.ChildModuleLogicalName.MappingName
    - Key
    - SubKey

Dépendre de ressources dans un module

Pour dépendre de ressources dans un module, utilisez leurs noms logiques qualifiés complets.

Resource1:
  DependsOn: ModuleLogicalName.ResourceLogicalName
Resource2:
  DependsOn: ModuleLogicalName.ChildModuleLogicalName.ResourceLogicalName

Dépendre d'un module

Lorsqu'une ressource ou un module dépend d'un autre module, toutes les ressources et tous les modules enfants du module dépendant deviennent des dépendances. Pour dépendre d'un module, utilisez son nom logique qualifié complet.

Resource1:
  DependsOn: ModuleLogicalName
Resource2:
  DependsOn: ModuleLogicalName.ChildModuleLogicalName

Considérations

Gardez à l'esprit les considérations suivantes lors de l'utilisation de modules :

Les modules sont gratuits. Vous êtes facturé uniquement pour les ressources résolues à partir du module vers la pile.
Si un modèle contient un module, les limites suivantes s'appliquent au modèle :
- Le nom d'un paramètre ne peut pas contenir la combinaison d'un point et de deux-points (.:).
- Le nom logique d'une ressource ne peut pas contenir de points (.).
- Le nom d'une sortie ne peut pas contenir de points (.).
- Le nom d'une condition ne peut pas contenir de perluètes (&).
- Vous ne pouvez pas ajouter les sections Transform et Workspace au modèle.
- Vous ne pouvez pas ajouter les sections Metadata et Count au module.
- Les noms logiques qualifiés complets des ressources et des modules, ainsi que les noms qualifiés complets des conditions et des mappages, doivent être uniques.
Les quotas ROS, tels que le nombre maximal de ressources autorisées dans une pile et la taille maximale d'un fichier de modèle, s'appliquent au modèle traité, indépendamment du fait que les ressources du modèle soient créées à partir de modules. Pour plus d'informations, consultez la rubrique Limites.
Les tags et les groupes de ressources que vous configurez pour une pile sont propagés à chaque ressource de pile créée à partir du module.
Lors du traitement du modèle, les données des sections Metadata et Rules du module sont ignorées.
Lors du traitement du module, les références dynamiques ne sont pas résolues. Les références dynamiques sont résolues lorsqu'une ressource unique est créée ou mise à jour lors d'une opération de pile. Pour plus d'informations sur les références dynamiques, consultez la rubrique Étape 2 : Créer un modèle ROS.
Les sorties du module ne sont pas propagées aux sorties du modèle. Vous pouvez créer une sortie de modèle et la référencer dans la sortie du module. Pour plus d'informations, consultez la rubrique Référencer les sorties d'un module.
Les paramètres du module ne sont pas propagés aux paramètres du modèle. Vous pouvez créer un paramètre de modèle et le référencer dans le paramètre du module. Pour plus d'informations, consultez la rubrique Spécifier une propriété de module à l'aide d'un paramètre de modèle.
Si vous modifiez la version par défaut du module pour lequel Version est défini sur default, aucune opération de mise à jour de pile n'est lancée.

Toutefois, la prochaine fois que vous utiliserez un modèle contenant ce module pour effectuer une opération de pile, telle qu'une mise à jour de pile, ROS utilisera la nouvelle version par défaut lors de l'opération.
Si vous créez une nouvelle version pour le module ou si vous supprimez la dernière version du module pour lequel Version est défini sur latest, aucune opération de mise à jour de pile n'est lancée.

Toutefois, la prochaine fois que vous utiliserez un modèle contenant ce module pour effectuer une opération de pile, telle qu'une mise à jour de pile, ROS utilisera la nouvelle dernière version lors de l'opération.
Lors des opérations de pile, ROS utilise les modules enregistrés dans le compte actuel, y compris les modules imbriqués dans d'autres modules.

Si vous utilisez un module dont plusieurs versions sont déployées sur différents comptes, des résultats différents seront retournés aux comptes, même si vous utilisez le même modèle.
Pour assurer la cohérence, si vous souhaitez inclure un module dans un modèle de pile afin de l'utiliser pour un groupe de piles, vous devez utiliser le même module sur tous les comptes où vous souhaitez déployer des instances de pile. Cela inclut les modules imbriqués dans d'autres modules. Pour plus d'informations, consultez la rubrique Groupes de piles.

Remarque
Si vous souhaitez développer les modules dans le compte auquel appartient le groupe de piles, vous devez sélectionner Whether to Expand Modules in Current Account dans la console ROS lors de la création ou de la mise à jour du groupe de piles.