diff --git a/docs/source-2.0/aws/aws-iam.rst b/docs/source-2.0/aws/aws-iam.rst index ee39923dbb8..91377a1fe3b 100644 --- a/docs/source-2.0/aws/aws-iam.rst +++ b/docs/source-2.0/aws/aws-iam.rst @@ -18,12 +18,17 @@ Smithy are automatically inferred. These can be disabled or augmented. For more information, see :ref:`deriving-condition-keys`. +.. _aws-iam_traits-principal: + +---------------- +Principal traits +---------------- + .. smithy-trait:: aws.iam#supportedPrincipalTypes .. _aws.iam#supportedPrincipalTypes-trait: ------------------------------------------ ``aws.iam#supportedPrincipalTypes`` trait ------------------------------------------ +========================================= Summary The `IAM principal types`_ that can use the service or operation. @@ -64,68 +69,6 @@ The following example defines two operations: operation OperationB {} -.. _aws-iam_traits-resources: - ---------------- -Resource traits ---------------- - -.. smithy-trait:: aws.iam#iamResource -.. _aws.iam#iamResource-trait: - -``aws.iam#iamResource`` trait -============================= - -Summary - Indicates properties of a Smithy resource in AWS IAM. -Trait selector - ``resource`` -Value type - ``structure`` - -The ``aws.iam#iamResource`` trait is a structure that supports the following -members: - -.. list-table:: - :header-rows: 1 - :widths: 10 20 70 - - * - Property - - Type - - Description - * - name - - ``string`` - - The name of the resource in AWS IAM. - * - relativeDocumentation - - ``string`` - - A relative URL path that defines more information about the resource - within a set of IAM-related documentation. - * - disableConditionKeyInheritance - - ``boolean`` - - When set to ``true``, decouples this IAM resource's condition keys from - those of its parent resource(s). This can be used in combination with - the :ref:`aws.iam#conditionKeys-trait` trait to isolate a resource's - condition keys from those of its parent(s). - -The following example defines a simple resource with a name in AWS IAM that -deviates from the :ref:`shape name of the shape ID ` of the resource. - -.. code-block:: smithy - - $version: "2" - - namespace smithy.example - - use aws.iam#iamResource - - @iamResource(name: "super") - resource SuperResource { - identifiers: { - superId: String, - } - } - - .. _aws-iam_traits-actions: ------------- @@ -246,11 +189,16 @@ contains the following properties: - The condition keys used for authorizing against this resource. +.. _aws-iam_traits-actions-deprecated-traits: + +Deprecated action traits +======================== + .. smithy-trait:: aws.iam#actionName .. _aws.iam#actionName-trait: ``aws.iam#actionName`` trait -============================ +---------------------------- .. danger:: This trait is deprecated. The ``name`` property of the @@ -295,7 +243,7 @@ The following example defines two operations: .. _aws.iam#actionPermissionDescription-trait: ``aws.iam#actionPermissionDescription`` trait -============================================= +--------------------------------------------- .. danger:: This trait is deprecated. The ``documentation`` property of the @@ -325,7 +273,7 @@ Value type .. _aws.iam#requiredActions-trait: ``aws.iam#requiredActions`` trait -================================= +--------------------------------- .. danger:: This trait is deprecated. The ``requiredActions`` property of the @@ -369,6 +317,68 @@ operation for it to complete successfully. @requiredActions(["otherservice:OtherOperation"]) operation MyOperation {} +.. _aws-iam_traits-resources: + +--------------- +Resource Traits +--------------- + +.. smithy-trait:: aws.iam#iamResource +.. _aws.iam#iamResource-trait: + +``aws.iam#iamResource`` trait +============================= + +Summary + Indicates properties of a Smithy resource in AWS IAM. +Trait selector + ``resource`` +Value type + ``structure`` + +The ``aws.iam#iamResource`` trait is a structure that supports the following +members: + +.. list-table:: + :header-rows: 1 + :widths: 10 20 70 + + * - Property + - Type + - Description + * - name + - ``string`` + - The name of the resource in AWS IAM. + * - relativeDocumentation + - ``string`` + - A relative URL path that defines more information about the resource + within a set of IAM-related documentation. + * - disableConditionKeyInheritance + - ``boolean`` + - When set to ``true``, decouples this IAM resource's condition keys from + those of its parent resource(s). This can be used in combination with + the :ref:`aws.iam#conditionKeys-trait` trait to isolate a resource's + condition keys from those of its parent(s). + +The following example defines a simple resource with a name in AWS IAM that +deviates from the :ref:`shape name of the shape ID ` of the resource. + +.. code-block:: smithy + + $version: "2" + + namespace smithy.example + + use aws.iam#iamResource + + @iamResource(name: "super") + resource SuperResource { + identifiers: { + superId: String, + } + } + + .. _aws-iam_traits-condition-keys: @@ -384,7 +394,8 @@ Condition key traits Summary Defines the set of condition keys that appear within a service in - addition to inferred and global condition keys. + addition to :ref:`inferred ` and global condition + keys. Trait selector ``service`` Value type @@ -433,7 +444,7 @@ Each condition key structure supports the following members: @service(sdkId: "My Value", arnNamespace: "myservice") @defineConditionKeys( - "otherservice:Bar": { + "myservice:Bar": { type: "String" documentation: "The Bar string" externalDocumentation: "http://example.com" @@ -449,49 +460,6 @@ Each condition key structure supports the following members: defined on the service. -.. _condition-key-types: - -Condition Key Types -------------------- - -The following table describes the available types a condition key can have. -Condition keys in IAM policies can be evaluated with `condition operators`_. - -.. list-table:: - :header-rows: 1 - :widths: 20 80 - - * - Type - - Description - * - ``ARN`` - - A String type that contains an `Amazon Resource Name (ARN)`_. - * - ``Binary`` - - A String type that contains base-64 encoded binary data. - * - ``Bool`` - - A general boolean type. - * - ``Date`` - - A String type that conforms to the ``datetime`` profile of `ISO 8601`_. - * - ``IPAddress`` - - A String type that conforms to :rfc:`4632`. - * - ``Numeric`` - - A general type for integers and floats. - * - ``String`` - - A general string type. - * - ``ArrayOfARN`` - - An unordered list of ARN types. - * - ``ArrayOfBinary`` - - An unordered list of Binary types. - * - ``ArrayOfBool`` - - An unordered list of Bool types. - * - ``ArrayOfDate`` - - An unordered list of Date types. - * - ``ArrayOfIPAddress`` - - An unordered list of IPAddress types. - * - ``ArrayOfNumeric`` - - An unordered list of Numeric types. - * - ``ArrayOfString`` - - An unordered list of String types. - .. smithy-trait:: aws.iam#conditionKeys .. _aws.iam#conditionKeys-trait: @@ -507,11 +475,11 @@ Value type ``list`` Condition keys derived automatically can be applied to a resource or operation -explicitly. Condition keys applied this way MUST be either inferred or -explicitly defined via the :ref:`aws.iam#defineConditionKeys-trait` trait. +explicitly. Condition keys applied this way MUST be either :ref:`inferred ` +or explicitly defined via the :ref:`aws.iam#defineConditionKeys-trait` trait. The following example's ``MyResource`` resource has the -``myservice:MyResourceFoo`` and ``otherservice:Bar`` condition keys. The +``myservice:MyResourceFoo`` and ``myservice:Bar`` condition keys. The ``MyOperation`` operation has the ``aws:region`` condition key. .. code-block:: smithy @@ -525,13 +493,13 @@ The following example's ``MyResource`` resource has the use aws.iam#conditionKeys @service(sdkId: "My Value", arnNamespace: "myservice") - @defineConditionKeys("otherservice:Bar": { type: "String" }) + @defineConditionKeys("myservice:Bar": { type: "String" }) service MyService { version: "2017-02-11" resources: [MyResource] } - @conditionKeys(["otherservice:Bar"]) + @conditionKeys(["myservice:Bar"]) resource MyResource { identifiers: {foo: String} operations: [MyOperation] @@ -546,85 +514,6 @@ The following example's ``MyResource`` resource has the without being defined on the service. -.. smithy-trait:: aws.iam#disableConditionKeyInference -.. _aws.iam#disableConditionKeyInference-trait: - -``aws.iam#disableConditionKeyInference`` trait -============================================== - -Summary - Declares that the condition keys of a resource should not be inferred. -Trait selector - ``:test(service, resource)`` -Value type - Annotation trait - -When a service is marked with the ``aws.iam#disableConditionKeyInference`` -trait, all the resources bound to the service will not have condition -keys automatically inferred from its identifiers and the identifiers -of its ancestors. - -The following example shows resources ``MyResource1`` and ``MyResource2`` -have had condition key inference disabled because they are bound to a -service marked with ``aws.iam#disableConditionKeyInference`` trait. - -.. code-block:: smithy - - $version: "2" - - namespace smithy.example - - use aws.api#service - use aws.iam#disableConditionKeyInference - - @service(sdkId: "My Value", arnNamespace: "myservice") - @disableConditionKeyInference - service MyService { - version: "2017-02-11" - resources: [MyResource1, MyResource2] - } - - resource MyResource1 { - identifiers: { - foo: String - } - } - - resource MyResource2 { - identifiers: { - foo: String - } - } - -A resource marked with the ``aws.iam#disableConditionKeyInference`` trait will -not have its condition keys automatically inferred from its identifiers and -the identifiers of its ancestors (if present.) - -The following example shows a resource, ``MyResource``, that has had its -condition key inference disabled. - -.. code-block:: smithy - - $version: "2" - - namespace smithy.example - - use aws.api#service - use aws.iam#disableConditionKeyInference - - @service(sdkId: "My Value", arnNamespace: "myservice") - service MyService { - version: "2017-02-11" - resources: [MyResource] - } - - @disableConditionKeyInference - resource MyResource { - identifiers: { - foo: String - bar: String - } - } .. smithy-trait:: aws.iam#serviceResolvedConditionKeys .. _aws.iam#serviceResolvedConditionKeys-trait: @@ -642,8 +531,8 @@ Value type All condition keys defined with the ``serviceResolvedConditionKeys`` trait MUST also be defined via the :ref:`aws.iam#defineConditionKeys-trait` trait. -Derived resource condition keys MUST NOT be included -with the ``serviceResolvedConditionKeys`` trait. +:ref:`Inferred resource condition keys ` MUST NOT be +included with the ``serviceResolvedConditionKeys`` trait. The following example defines two service-specific condition keys: @@ -715,9 +604,134 @@ explicitly binds ``ActionContextKey1`` to the field ``key``. } +.. smithy-trait:: aws.iam#disableConditionKeyInference +.. _aws.iam#disableConditionKeyInference-trait: + +``aws.iam#disableConditionKeyInference`` trait +============================================== + +Summary + Declares that the condition keys of a resource should not be + :ref:`inferred `. +Trait selector + ``:test(service, resource)`` +Value type + Annotation trait + +When a service is marked with the ``aws.iam#disableConditionKeyInference`` +trait, all the resources bound to the service will not have condition +keys automatically inferred from its identifiers and the identifiers +of its ancestors. + +The following example shows resources ``MyResource1`` and ``MyResource2`` +have had condition key inference disabled because they are bound to a +service marked with ``aws.iam#disableConditionKeyInference`` trait. + +.. code-block:: smithy + + $version: "2" + + namespace smithy.example + + use aws.api#service + use aws.iam#disableConditionKeyInference + + @service(sdkId: "My Value", arnNamespace: "myservice") + @disableConditionKeyInference + service MyService { + version: "2017-02-11" + resources: [MyResource1, MyResource2] + } + + resource MyResource1 { + identifiers: { + foo: String + } + } + + resource MyResource2 { + identifiers: { + foo: String + } + } + +A resource marked with the ``aws.iam#disableConditionKeyInference`` trait will +not have its condition keys automatically inferred from its identifiers and +the identifiers of its ancestors. if present. + +The following example shows a resource, ``MyResource``, that has condition key +inference disabled. + +.. code-block:: smithy + + $version: "2" + + namespace smithy.example + + use aws.api#service + use aws.iam#disableConditionKeyInference + + @service(sdkId: "My Value", arnNamespace: "myservice") + service MyService { + version: "2017-02-11" + resources: [MyResource] + } + + @disableConditionKeyInference + resource MyResource { + identifiers: { + foo: String + bar: String + } + } + + +.. _condition-key-types: + +Condition Key Types +======================= + +The following table describes the available types a condition key can have. +Condition keys in IAM policies can be evaluated with `condition operators`_. + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - Type + - Description + * - ``ARN`` + - A String type that contains an `Amazon Resource Name (ARN)`_. + * - ``Binary`` + - A String type that contains base-64 encoded binary data. + * - ``Bool`` + - A general boolean type. + * - ``Date`` + - A String type that conforms to the ``datetime`` profile of `ISO 8601`_. + * - ``IPAddress`` + - A String type that conforms to :rfc:`4632`. + * - ``Numeric`` + - A general type for integers and floats. + * - ``String`` + - A general string type. + * - ``ArrayOfARN`` + - An unordered list of ARN types. + * - ``ArrayOfBinary`` + - An unordered list of Binary types. + * - ``ArrayOfBool`` + - An unordered list of Bool types. + * - ``ArrayOfDate`` + - An unordered list of Date types. + * - ``ArrayOfIPAddress`` + - An unordered list of IPAddress types. + * - ``ArrayOfNumeric`` + - An unordered list of Numeric types. + * - ``ArrayOfString`` + - An unordered list of String types. + .. _deriving-condition-keys: -Deriving Condition Keys +Deriving condition keys ======================= Smithy will automatically derive condition key information for a service, as @@ -747,13 +761,13 @@ Given the following model, use aws.iam#iamResource @service(sdkId: "My Value", arnNamespace: "myservice") - @defineConditionKeys("otherservice:Bar": { type: "String" }) + @defineConditionKeys("myservice:Bar": { type: "String" }) service MyService { version: "2017-02-11" resources: [MyResource] } - @conditionKeys(["otherservice:Bar"]) + @conditionKeys(["myservice:Bar"]) resource MyResource { identifiers: {foo: String} operations: [MyOperation] @@ -792,11 +806,11 @@ The computed condition keys for the service are: * - ``MyResource`` - * ``myservice:MyResourceFoo`` - * ``otherservice:Bar`` + * ``myservice:Bar`` * - ``InnerResource`` - * ``myservice:MyResourceFoo`` - * ``otherservice:Bar`` + * ``myservice:Bar`` * ``myservice:InnerResourceYum`` * - ``MyDetachedResource`` - None @@ -807,7 +821,6 @@ The computed condition keys for the service are: - * ``aws:region`` - .. _AWS Identity and Access Management: https://aws.amazon.com/iam/ .. _Condition keys: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html .. _Actions: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_action.html diff --git a/docs/source-2.0/guides/generating-cloudformation-resources.rst b/docs/source-2.0/guides/generating-cloudformation-resources.rst index 412bfaee536..2953b2d2225 100644 --- a/docs/source-2.0/guides/generating-cloudformation-resources.rst +++ b/docs/source-2.0/guides/generating-cloudformation-resources.rst @@ -292,9 +292,10 @@ disableHandlerPermissionGeneration (``boolean``) Sets whether to disable generating ``handler`` ``permission`` lists for Resource Schemas. By default, handler permissions lists are automatically added to schemas based on :ref:`lifecycle-operations` and permissions - listed in the :ref:`aws.iam#requiredActions-trait` on the operation. See - `the handlers section`_ in the CloudFormation Resource Schemas - documentation for more information. + listed in the :ref:`requiredActions property of the aws.iam#iamAction + trait ` on the operation. See `the handlers + section`_ in the CloudFormation Resource Schemas documentation for more + information. .. code-block:: json @@ -312,7 +313,8 @@ disableHandlerPermissionGeneration (``boolean``) CloudFormation Resource Schema handlers determine what provisioning actions can be performed for the resource. The handlers utilized by CloudFormation align with some :ref:`lifecycle-operations`. These operations can also - define other permission actions required to invoke them with the :ref:`aws.iam#requiredActions-trait`. + define other permission actions required to invoke them with the :ref:`requiredActions + property of the aws.iam#iamAction trait ` When handler permission generation is enabled, all the actions required to invoke the operations related to the handler, including the actions for the