From 1c1b256112e52b5c04f29bb5c17106f8c82cbe91 Mon Sep 17 00:00:00 2001 From: kstich Date: Tue, 9 Jan 2024 13:45:45 -0800 Subject: [PATCH 1/2] Improve deprecation of IAM Action traits This commit formally deprecates the traits superseded by `@iamAction` in Java code. Methods are added to IamAction to aid users in the resolution of properties. A resolution aid is also added to IamResource. --- .../mappers/HandlerPermissionMapper.java | 8 +- .../aws/iam/traits/ActionNameTrait.java | 6 + .../ActionPermissionDescriptionTrait.java | 5 +- .../smithy/aws/iam/traits/IamActionTrait.java | 70 ++++++++++++ .../aws/iam/traits/IamActionValidator.java | 1 + .../aws/iam/traits/IamResourceTrait.java | 21 ++++ .../aws/iam/traits/RequiredActionsTrait.java | 6 + .../aws/iam/traits/ActionNameTraitTest.java | 7 +- .../ActionPermissionDescriptionTraitTest.java | 1 + .../aws/iam/traits/IamActionTraitTest.java | 103 +++++++++++++++++- .../aws/iam/traits/IamResourceTraitTest.java | 21 +++- .../iam/traits/RequiredActionsTraitTest.java | 1 + .../amazon/smithy/model/loader/Version.java | 2 +- 13 files changed, 238 insertions(+), 14 deletions(-) diff --git a/smithy-aws-cloudformation/src/main/java/software/amazon/smithy/aws/cloudformation/schema/fromsmithy/mappers/HandlerPermissionMapper.java b/smithy-aws-cloudformation/src/main/java/software/amazon/smithy/aws/cloudformation/schema/fromsmithy/mappers/HandlerPermissionMapper.java index 4a671f949a7..a32bbc516e8 100644 --- a/smithy-aws-cloudformation/src/main/java/software/amazon/smithy/aws/cloudformation/schema/fromsmithy/mappers/HandlerPermissionMapper.java +++ b/smithy-aws-cloudformation/src/main/java/software/amazon/smithy/aws/cloudformation/schema/fromsmithy/mappers/HandlerPermissionMapper.java @@ -23,7 +23,6 @@ import software.amazon.smithy.aws.cloudformation.schema.model.Handler; import software.amazon.smithy.aws.cloudformation.schema.model.ResourceSchema; import software.amazon.smithy.aws.iam.traits.IamActionTrait; -import software.amazon.smithy.aws.iam.traits.RequiredActionsTrait; import software.amazon.smithy.aws.traits.ServiceTrait; import software.amazon.smithy.model.Model; import software.amazon.smithy.model.shapes.OperationShape; @@ -31,7 +30,6 @@ import software.amazon.smithy.model.shapes.ServiceShape; import software.amazon.smithy.model.shapes.ShapeId; import software.amazon.smithy.model.traits.NoReplaceTrait; -import software.amazon.smithy.utils.ListUtils; import software.amazon.smithy.utils.SetUtils; import software.amazon.smithy.utils.SmithyInternalApi; @@ -114,11 +112,7 @@ private Set getPermissionsEntriesForOperation(Model model, ServiceShape permissionsEntries.add(operationActionName); // Add all the other required actions for the operation. - permissionsEntries.addAll(operation.getTrait(IamActionTrait.class) - .map(IamActionTrait::getRequiredActions) - .orElseGet(() -> operation.getTrait(RequiredActionsTrait.class) - .map(RequiredActionsTrait::getValues) - .orElse(ListUtils.of()))); + permissionsEntries.addAll(IamActionTrait.resolveRequiredActions(operation)); return permissionsEntries; } } diff --git a/smithy-aws-iam-traits/src/main/java/software/amazon/smithy/aws/iam/traits/ActionNameTrait.java b/smithy-aws-iam-traits/src/main/java/software/amazon/smithy/aws/iam/traits/ActionNameTrait.java index fcf491aca1c..c0afede91fb 100644 --- a/smithy-aws-iam-traits/src/main/java/software/amazon/smithy/aws/iam/traits/ActionNameTrait.java +++ b/smithy-aws-iam-traits/src/main/java/software/amazon/smithy/aws/iam/traits/ActionNameTrait.java @@ -10,6 +10,12 @@ import software.amazon.smithy.model.shapes.ShapeId; import software.amazon.smithy.model.traits.StringTrait; +/** + * Use the {@code @iamAction} trait's {@code name} property instead. + * + * @deprecated As of release 1.44.0, replaced by {@link IamActionTrait#resolveActionName}. + */ +@Deprecated public final class ActionNameTrait extends StringTrait { public static final ShapeId ID = ShapeId.from("aws.iam#actionName"); diff --git a/smithy-aws-iam-traits/src/main/java/software/amazon/smithy/aws/iam/traits/ActionPermissionDescriptionTrait.java b/smithy-aws-iam-traits/src/main/java/software/amazon/smithy/aws/iam/traits/ActionPermissionDescriptionTrait.java index c818afdb10e..331357e5370 100644 --- a/smithy-aws-iam-traits/src/main/java/software/amazon/smithy/aws/iam/traits/ActionPermissionDescriptionTrait.java +++ b/smithy-aws-iam-traits/src/main/java/software/amazon/smithy/aws/iam/traits/ActionPermissionDescriptionTrait.java @@ -20,8 +20,11 @@ import software.amazon.smithy.model.traits.StringTrait; /** - * Defines the description of what providing access to an operation entails. + * Use the {@code @iamAction} trait's {@code documentation} property instead. + * + * @deprecated As of release 1.44.0, replaced by {@link IamActionTrait#resolveActionDocumentation}. */ +@Deprecated public final class ActionPermissionDescriptionTrait extends StringTrait { public static final ShapeId ID = ShapeId.from("aws.iam#actionPermissionDescription"); diff --git a/smithy-aws-iam-traits/src/main/java/software/amazon/smithy/aws/iam/traits/IamActionTrait.java b/smithy-aws-iam-traits/src/main/java/software/amazon/smithy/aws/iam/traits/IamActionTrait.java index 67377e186f3..63a81ed1f7a 100644 --- a/smithy-aws-iam-traits/src/main/java/software/amazon/smithy/aws/iam/traits/IamActionTrait.java +++ b/smithy-aws-iam-traits/src/main/java/software/amazon/smithy/aws/iam/traits/IamActionTrait.java @@ -19,11 +19,15 @@ import java.util.Optional; import software.amazon.smithy.model.node.Node; import software.amazon.smithy.model.node.NodeMapper; +import software.amazon.smithy.model.shapes.OperationShape; import software.amazon.smithy.model.shapes.ShapeId; import software.amazon.smithy.model.traits.AbstractTrait; import software.amazon.smithy.model.traits.AbstractTraitBuilder; +import software.amazon.smithy.model.traits.DocumentationTrait; import software.amazon.smithy.model.traits.Trait; import software.amazon.smithy.utils.BuilderRef; +import software.amazon.smithy.utils.FunctionalUtils; +import software.amazon.smithy.utils.ListUtils; import software.amazon.smithy.utils.SmithyBuilder; import software.amazon.smithy.utils.ToSmithyBuilder; @@ -60,6 +64,27 @@ public Optional getName() { return Optional.ofNullable(name); } + /** + * Resolves the IAM action name for the given operation. Uses the following + * resolution order: + * + *
    + *
  1. Value of the {@code @iamAction} trait's {@code name} property
    2. + *
  2. Value of the {@code @actionName} trait
    3. + *
  3. The operation's name
    4. + *
+ * + * @param operation the operation to resolve a name for. + * @return The resolved action name. + */ + @SuppressWarnings("deprecation") + public static String resolveActionName(OperationShape operation) { + return operation.getTrait(IamActionTrait.class).flatMap(IamActionTrait::getName) + .orElseGet(() -> operation.getTrait(ActionNameTrait.class) + .map(ActionNameTrait::getValue) + .orElseGet(() -> operation.getId().getName())); + } + /** * Gets the description of what granting the user permission to * invoke an operation would entail. @@ -70,6 +95,29 @@ public Optional getDocumentation() { return Optional.ofNullable(documentation); } + /** + * Resolves the IAM action documentation for the given operation. Uses the following + * resolution order: + * + *
    + *
  1. Value of the {@code @iamAction} trait's {@code documentation} property
    2. + *
  2. Value of the {@code @actionPermissionDescription} trait
    3. + *
  3. Value of the {@code @documentation} trait
    4. + *
+ * + * @param operation the operation to resolve documentation for. + * @return The resolved action documentation. + */ + @SuppressWarnings("deprecation") + public static String resolveActionDocumentation(OperationShape operation) { + return operation.getTrait(IamActionTrait.class).flatMap(IamActionTrait::getDocumentation) + .orElseGet(() -> operation.getTrait(ActionPermissionDescriptionTrait.class) + .map(ActionPermissionDescriptionTrait::getValue) + .orElseGet(() -> operation.getTrait(DocumentationTrait.class) + .map(DocumentationTrait::getValue) + .orElse(null))); + } + /** * Gets the relative URL path for the action within a set of * IAM-related documentation. @@ -90,6 +138,28 @@ public List getRequiredActions() { return requiredActions; } + /** + * Resolves the IAM action required actions for the given operation. Uses the following + * resolution order: + * + *
    + *
  1. Value of the {@code @iamAction} trait's {@code requiredActions} property
    2. + *
  2. Value of the {@code @requiredActions} trait
    3. + *
  3. An empty list.
    4. + *
+ * + * @param operation the operation to resolve required actions for. + * @return The resolved required actions. + */ + @SuppressWarnings("deprecation") + public static List resolveRequiredActions(OperationShape operation) { + return operation.getTrait(IamActionTrait.class).map(IamActionTrait::getRequiredActions) + .filter(FunctionalUtils.not(List::isEmpty)) + .orElseGet(() -> operation.getTrait(RequiredActionsTrait.class) + .map(RequiredActionsTrait::getValues) + .orElse(ListUtils.of())); + } + /** * Gets the resources an IAM action can be authorized against. * diff --git a/smithy-aws-iam-traits/src/main/java/software/amazon/smithy/aws/iam/traits/IamActionValidator.java b/smithy-aws-iam-traits/src/main/java/software/amazon/smithy/aws/iam/traits/IamActionValidator.java index b04a2a26889..9c5de2802a3 100644 --- a/smithy-aws-iam-traits/src/main/java/software/amazon/smithy/aws/iam/traits/IamActionValidator.java +++ b/smithy-aws-iam-traits/src/main/java/software/amazon/smithy/aws/iam/traits/IamActionValidator.java @@ -32,6 +32,7 @@ public List validate(Model model) { return events; } + @SuppressWarnings("deprecation") private List validateDuplicateTraits(OperationShape operation, IamActionTrait trait) { List events = new ArrayList<>(); if (operation.hasTrait(ActionNameTrait.ID) && trait.getName().isPresent()) { diff --git a/smithy-aws-iam-traits/src/main/java/software/amazon/smithy/aws/iam/traits/IamResourceTrait.java b/smithy-aws-iam-traits/src/main/java/software/amazon/smithy/aws/iam/traits/IamResourceTrait.java index 1787b320d95..74e68fab69b 100644 --- a/smithy-aws-iam-traits/src/main/java/software/amazon/smithy/aws/iam/traits/IamResourceTrait.java +++ b/smithy-aws-iam-traits/src/main/java/software/amazon/smithy/aws/iam/traits/IamResourceTrait.java @@ -18,6 +18,7 @@ import java.util.Optional; import software.amazon.smithy.model.node.Node; import software.amazon.smithy.model.node.NodeMapper; +import software.amazon.smithy.model.shapes.ResourceShape; import software.amazon.smithy.model.shapes.ShapeId; import software.amazon.smithy.model.traits.AbstractTrait; import software.amazon.smithy.model.traits.AbstractTraitBuilder; @@ -52,6 +53,26 @@ public Optional getName() { return Optional.ofNullable(name); } + + + /** + * Resolves the IAM resource name for the given resource. Uses the following + * resolution order: + * + *
    + *
  1. Value of the {@code @iamResource} trait's {@code name} property
    2. + *
  2. The resource's name
    3. + *
+ * + * @param resource the resource to resolve a name for. + * @return The resolved resource name. + */ + public static String resolveResourceName(ResourceShape resource) { + return resource.getTrait(IamResourceTrait.class) + .flatMap(IamResourceTrait::getName) + .orElse(resource.getId().getName()); + } + /** * Get the relative URL path that defines more information about the resource * within a set of IAM-related documentation. diff --git a/smithy-aws-iam-traits/src/main/java/software/amazon/smithy/aws/iam/traits/RequiredActionsTrait.java b/smithy-aws-iam-traits/src/main/java/software/amazon/smithy/aws/iam/traits/RequiredActionsTrait.java index 4a434b1b7c7..f008b5eaec3 100644 --- a/smithy-aws-iam-traits/src/main/java/software/amazon/smithy/aws/iam/traits/RequiredActionsTrait.java +++ b/smithy-aws-iam-traits/src/main/java/software/amazon/smithy/aws/iam/traits/RequiredActionsTrait.java @@ -22,6 +22,12 @@ import software.amazon.smithy.model.traits.StringListTrait; import software.amazon.smithy.utils.ToSmithyBuilder; +/** + * Use the {@code @iamAction} trait's {@code requiredActions} property instead. + * + * @deprecated As of release 1.44.0, replaced by {@link IamActionTrait#resolveRequiredActions}. + */ +@Deprecated public final class RequiredActionsTrait extends StringListTrait implements ToSmithyBuilder { public static final ShapeId ID = ShapeId.from("aws.iam#requiredActions"); diff --git a/smithy-aws-iam-traits/src/test/java/software/amazon/smithy/aws/iam/traits/ActionNameTraitTest.java b/smithy-aws-iam-traits/src/test/java/software/amazon/smithy/aws/iam/traits/ActionNameTraitTest.java index 0b39e3b1cd4..274ad449be5 100644 --- a/smithy-aws-iam-traits/src/test/java/software/amazon/smithy/aws/iam/traits/ActionNameTraitTest.java +++ b/smithy-aws-iam-traits/src/test/java/software/amazon/smithy/aws/iam/traits/ActionNameTraitTest.java @@ -5,16 +5,17 @@ package software.amazon.smithy.aws.iam.traits; +import static org.hamcrest.MatcherAssert.assertThat; +import static org.hamcrest.Matchers.equalTo; + import org.junit.jupiter.api.Test; import software.amazon.smithy.model.Model; import software.amazon.smithy.model.shapes.Shape; import software.amazon.smithy.model.shapes.ShapeId; -import static org.hamcrest.MatcherAssert.assertThat; -import static org.hamcrest.Matchers.equalTo; - public class ActionNameTraitTest { @Test + @SuppressWarnings("deprecation") public void loadsFromModel() { Model result = Model.assembler() .discoverModels(getClass().getClassLoader()) diff --git a/smithy-aws-iam-traits/src/test/java/software/amazon/smithy/aws/iam/traits/ActionPermissionDescriptionTraitTest.java b/smithy-aws-iam-traits/src/test/java/software/amazon/smithy/aws/iam/traits/ActionPermissionDescriptionTraitTest.java index 426e9cada76..5ab161cec1c 100644 --- a/smithy-aws-iam-traits/src/test/java/software/amazon/smithy/aws/iam/traits/ActionPermissionDescriptionTraitTest.java +++ b/smithy-aws-iam-traits/src/test/java/software/amazon/smithy/aws/iam/traits/ActionPermissionDescriptionTraitTest.java @@ -28,6 +28,7 @@ public class ActionPermissionDescriptionTraitTest { @Test + @SuppressWarnings("deprecation") public void createsTrait() { Node node = Node.from("Foo baz bar"); TraitFactory provider = TraitFactory.createServiceFactory(); diff --git a/smithy-aws-iam-traits/src/test/java/software/amazon/smithy/aws/iam/traits/IamActionTraitTest.java b/smithy-aws-iam-traits/src/test/java/software/amazon/smithy/aws/iam/traits/IamActionTraitTest.java index e0cad6b3e78..d4f40f661b4 100644 --- a/smithy-aws-iam-traits/src/test/java/software/amazon/smithy/aws/iam/traits/IamActionTraitTest.java +++ b/smithy-aws-iam-traits/src/test/java/software/amazon/smithy/aws/iam/traits/IamActionTraitTest.java @@ -18,15 +18,21 @@ import static org.hamcrest.MatcherAssert.assertThat; import static org.hamcrest.Matchers.contains; import static org.hamcrest.Matchers.containsInAnyOrder; +import static org.hamcrest.Matchers.empty; import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNull; import static org.junit.jupiter.api.Assertions.assertTrue; import org.junit.jupiter.api.Test; import software.amazon.smithy.model.Model; +import software.amazon.smithy.model.shapes.OperationShape; import software.amazon.smithy.model.shapes.Shape; import software.amazon.smithy.model.shapes.ShapeId; +import software.amazon.smithy.model.traits.DocumentationTrait; public class IamActionTraitTest { + private static final ShapeId ID = ShapeId.from("smithy.example#Foo"); + @Test public void loadsFromModel() { Model result = Model.assembler() @@ -35,7 +41,7 @@ public void loadsFromModel() { .assemble() .unwrap(); - Shape fooOperation = result.expectShape(ShapeId.from("smithy.example#Foo")); + Shape fooOperation = result.expectShape(ID); assertTrue(fooOperation.hasTrait(IamActionTrait.class)); IamActionTrait trait = fooOperation.expectTrait(IamActionTrait.class); @@ -54,4 +60,99 @@ public void loadsFromModel() { assertTrue(actionResources.getOptional().containsKey("baz")); assertTrue(actionResources.getOptional().get("baz").getConditionKeys().isEmpty()); } + + @Test + @SuppressWarnings("deprecation") + public void prefersIamActionTraitName() { + OperationShape op = OperationShape.builder().id(ID) + .addTrait(IamActionTrait.builder().name("ThisOne").build()) + .addTrait(new ActionNameTrait("Unused")) + .build(); + + assertEquals("ThisOne", IamActionTrait.resolveActionName(op)); + } + + @Test + @SuppressWarnings("deprecation") + public void usesDeprecatedActionNameTrait() { + OperationShape op = OperationShape.builder().id(ID) + .addTrait(new ActionNameTrait("ThisOne")) + .build(); + + assertEquals("ThisOne", IamActionTrait.resolveActionName(op)); + } + + @Test + public void defaultsToOperationName() { + OperationShape op = OperationShape.builder().id(ID).build(); + + assertEquals("Foo", IamActionTrait.resolveActionName(op)); + } + + @Test + @SuppressWarnings("deprecation") + public void prefersIamActionTraitDocumentation() { + OperationShape op = OperationShape.builder().id(ID) + .addTrait(IamActionTrait.builder().documentation("ThisOne").build()) + .addTrait(new ActionPermissionDescriptionTrait("Unused")) + .addTrait(new DocumentationTrait("Unused")) + .build(); + + assertEquals("ThisOne", IamActionTrait.resolveActionDocumentation(op)); + } + + @Test + @SuppressWarnings("deprecation") + public void usesDeprecatedActionPermissionDescriptionTrait() { + OperationShape op = OperationShape.builder().id(ID) + .addTrait(new ActionPermissionDescriptionTrait("ThisOne")) + .addTrait(new DocumentationTrait("Unused")) + .build(); + + assertEquals("ThisOne", IamActionTrait.resolveActionDocumentation(op)); + } + + @Test + public void usesDocumentationTrait() { + OperationShape op = OperationShape.builder().id(ID) + .addTrait(new DocumentationTrait("ThisOne")) + .build(); + + assertEquals("ThisOne", IamActionTrait.resolveActionDocumentation(op)); + } + + @Test + public void defaultsToNoDocumentation() { + OperationShape op = OperationShape.builder().id(ID).build(); + + assertNull(IamActionTrait.resolveActionDocumentation(op)); + } + + @Test + @SuppressWarnings("deprecation") + public void prefersIamActionTraitRequiredActions() { + OperationShape op = OperationShape.builder().id(ID) + .addTrait(IamActionTrait.builder().addRequiredAction("ThisOne").build()) + .addTrait(new ActionNameTrait("Unused")) + .build(); + + assertThat(IamActionTrait.resolveRequiredActions(op), contains("ThisOne")); + } + + @Test + @SuppressWarnings("deprecation") + public void usesDeprecatedRequiredActionsTrait() { + OperationShape op = OperationShape.builder().id(ID) + .addTrait(RequiredActionsTrait.builder().addValue("ThisOne").build()) + .build(); + + assertThat(IamActionTrait.resolveRequiredActions(op), contains("ThisOne")); + } + + @Test + public void defaultsToEmptyRequiredActions() { + OperationShape op = OperationShape.builder().id(ID).build(); + + assertThat(IamActionTrait.resolveRequiredActions(op), empty()); + } } diff --git a/smithy-aws-iam-traits/src/test/java/software/amazon/smithy/aws/iam/traits/IamResourceTraitTest.java b/smithy-aws-iam-traits/src/test/java/software/amazon/smithy/aws/iam/traits/IamResourceTraitTest.java index dc03eb967f1..eceacac1a73 100644 --- a/smithy-aws-iam-traits/src/test/java/software/amazon/smithy/aws/iam/traits/IamResourceTraitTest.java +++ b/smithy-aws-iam-traits/src/test/java/software/amazon/smithy/aws/iam/traits/IamResourceTraitTest.java @@ -21,10 +21,13 @@ import org.junit.jupiter.api.Test; import software.amazon.smithy.model.Model; +import software.amazon.smithy.model.shapes.ResourceShape; import software.amazon.smithy.model.shapes.Shape; import software.amazon.smithy.model.shapes.ShapeId; public class IamResourceTraitTest { + private static final ShapeId ID = ShapeId.from("smithy.example#SuperResource"); + @Test public void loadsFromModel() { Model result = Model.assembler() @@ -33,11 +36,27 @@ public void loadsFromModel() { .assemble() .unwrap(); - Shape superResource = result.expectShape(ShapeId.from("smithy.example#SuperResource")); + Shape superResource = result.expectShape(ID); assertTrue(superResource.hasTrait(IamResourceTrait.class)); assertEquals(superResource.expectTrait(IamResourceTrait.class).getName().get(), "super"); assertEquals(superResource.expectTrait(IamResourceTrait.class).getRelativeDocumentation().get(), "API-Super.html"); assertFalse(superResource.expectTrait(IamResourceTrait.class).isDisableConditionKeyInheritance()); } + + @Test + public void prefersIamResourceTraitName() { + ResourceShape resource = ResourceShape.builder().id(ID) + .addTrait(IamResourceTrait.builder().name("ThisOne").build()) + .build(); + + assertEquals("ThisOne", IamResourceTrait.resolveResourceName(resource)); + } + + @Test + public void defaultsToResourceName() { + ResourceShape resource = ResourceShape.builder().id(ID).build(); + + assertEquals("SuperResource", IamResourceTrait.resolveResourceName(resource)); + } } diff --git a/smithy-aws-iam-traits/src/test/java/software/amazon/smithy/aws/iam/traits/RequiredActionsTraitTest.java b/smithy-aws-iam-traits/src/test/java/software/amazon/smithy/aws/iam/traits/RequiredActionsTraitTest.java index aba961b71d3..d4b2569d255 100644 --- a/smithy-aws-iam-traits/src/test/java/software/amazon/smithy/aws/iam/traits/RequiredActionsTraitTest.java +++ b/smithy-aws-iam-traits/src/test/java/software/amazon/smithy/aws/iam/traits/RequiredActionsTraitTest.java @@ -26,6 +26,7 @@ public class RequiredActionsTraitTest { @Test + @SuppressWarnings("deprecation") public void loadsFromModel() { Model result = Model.assembler() .discoverModels(getClass().getClassLoader()) diff --git a/smithy-model/src/main/java/software/amazon/smithy/model/loader/Version.java b/smithy-model/src/main/java/software/amazon/smithy/model/loader/Version.java index a9de96dcbf3..9f53679024a 100644 --- a/smithy-model/src/main/java/software/amazon/smithy/model/loader/Version.java +++ b/smithy-model/src/main/java/software/amazon/smithy/model/loader/Version.java @@ -171,7 +171,7 @@ boolean isDeprecated() { } @Override - @SuppressWarnings("deprecated") + @SuppressWarnings("deprecation") ValidationEvent validateVersionedTrait(ShapeId target, ShapeId traitId, Node value) { if (traitId.equals(BoxTrait.ID)) { return ValidationEvent.builder() From 3127144ae61d03a51ba47e8f0404d7ef471894b2 Mon Sep 17 00:00:00 2001 From: Josh Joy Date: Mon, 27 Nov 2023 09:39:45 -0500 Subject: [PATCH 2/2] Update IAM trait documentation 1. Layout to match PARC order 2. Tidy the condition key traits layout 3. Update to use myservice instead of otherservice for condition keys, as condition keys should reference the same service. --- docs/source-2.0/aws/aws-iam.rst | 421 +++++++++--------- .../generating-cloudformation-resources.rst | 10 +- 2 files changed, 223 insertions(+), 208 deletions(-) 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