Add recommendation for scalar output to v3 migration guide (#1448)

#1445 and
#1446 introduced new scalar
properties as a workaround to the breaking Node.js SDK changes.

This documents those in the migration guide.

docs/eks-v3-migration.md

@@ -38,7 +38,7 @@ AWS recently announced the deprecation of two features used by default in Pulumi
 ## VPC CNI Component changes
 
 The VPC CNI cluster component is now configured as an EKS addon as mentioned in the “New Features” section above. This brings the following changes:
-- Removed `enableIpv6` input property. The component automatically configures the IP version now depending on whether the cluster is running in IPv4 or IPv6 mode.  
+- Removed `enableIpv6` input property. The component automatically configures the IP version now, depending on whether the cluster is running in IPv4 or IPv6 mode.
 - Removed `image`, `initImage`, `nodeAgentImage` input properties. The component now automatically selects an image registry in the cluster’s region to pull the images from.
 
 During the update, you'll observe two key changes:
@@ -142,22 +142,55 @@ A step-by-step migration guide can be found [here](https://github.com/pulumi/pul
 We currently recommend users create all new clusters with the `API` authentication mode.
 More details about this can be found [here](https://docs.aws.amazon.com/eks/latest/userguide/grant-k8s-access.html).
 
-## Nodejs SDK changes
+## Node.js SDK changes
 
-The Nodejs SDK is updated to use state of the art Pulumi tooling, improving stability, documentation and security. The update requires the following changes to programs:
-
-- Properties of the components are now outputs instead of plain types. Notable cases where you need to change your program are:
-  - The [`Cluster::getKubeConfig`](https://www.pulumi.com/registry/packages/eks/api-docs/cluster/#method_GetKubeconfig) method now returns an output.  
-  - Creating an IRSA based IAM role now requires you to use `apply` for accessing the OIDC provider ARN and URL. An example of how this works can be found [here](https://github.com/pulumi/pulumi-eks/blob/release-3.x.x/examples/oidc-iam-sa/index.ts).  
-  - `k8s.Provider` will be deleted if not referenced (no impact, but it will appear in the diff)
-  - `clusterOidcProvider` is an output now. `getKubeConfig` returns an output now  
-- The deprecated input property `deployDashboard` of the `Cluster` component has been removed from the Nodejs SDK. This has already been removed from the other SDKs in the past. If you’d like to continue using it, you can adopt the existing code into your own program from [here](https://github.com/pulumi/pulumi-eks/blob/bcc170e72b802a78e7f0a99bc92316a5f8a62b0e/nodejs/eks/dashboard.ts).
+The Node.js SDK is updated to use state of the art Pulumi tooling, improving stability, documentation and security. The update requires the following changes to programs:
+- Properties of the components are now outputs instead of plain types. Accessing those optional resource outputs now requires using `apply`. More details about this in the next section. 
+- The [`Cluster.getKubeConfig`](https://www.pulumi.com/registry/packages/eks/api-docs/cluster/#method_GetKubeconfig) method now returns an output. 
+- The `cluster.provider` will be deleted if not referenced (no impact, but it will appear in the diff)
+- The deprecated input property `deployDashboard` of the `Cluster` component has been removed from the Node.js SDK. This has already been removed from the other SDKs in the past. If you’d like to continue using it, you can adopt the existing code into your own program from [here](https://github.com/pulumi/pulumi-eks/blob/bcc170e72b802a78e7f0a99bc92316a5f8a62b0e/nodejs/eks/dashboard.ts).
 - The `createManagedNodeGroup` function will now create an Pulumi EKS `ManagedNodeGroup` instead of creating the underlying `aws.eks.NodeGroup` resource directly. During the upgrade to Pulumi EKS v3 you'll see the additional wrapper component being created.
 - The capitalization of the `AuthenticationMode` and `AccessEntryType` enum values has been aligned with other providers (e.g. `AuthenticationMode.API` => `AuthenticationMode.Api`). The previous values have been marked as deprecated and now point to their new counterparts.
 
+### Properties of the components are now outputs instead of plain types
+All properties of components in the Node.js SDK are now wrapped in `Output`. This aligns it with other language SDKs but introduces breaking changes for optional resource properties.
+Accessing those optional resource outputs now requires using `apply`.
+
+We added convenient access properties for frequently used outputs:
+- Creating an IRSA based IAM role now requires using `apply` for accessing the cluster's OIDC provider ARN and URL. Alternatively, use the new top level properties `oidcProviderArn` and `oidcIssuer`. An example can be found [here](https://github.com/pulumi/pulumi-eks/blob/release-3.x.x/examples/oidc-iam-sa/index.ts).
+- Accessing a cluster's `clusterSecurityGroup`, `nodeSecurityGroup`, and `eksClusterIngressRule` requires using `apply`. Alternatively, use the new top-level properties. The `NodeGroup` and `NodeGroupV2` components were updated to also take those new top-level properties as inputs.
+  - Use the following top-level properties of the `Cluster` component:
+    - `clusterSecurityGroupId` instead of `cluster.clusterSecurityGroup.id`
+    - `nodeSecurityGroupId` instead of `cluster.nodeSecurityGroup.id`
+    - `clusterIngressRuleId` instead of `cluster.eksClusterIngressRule.id`
+  - When passing these to the `NodeGroup` and `NodeGroupV2` components use the following inputs:
+    - `nodeSecurityGroupId` instead of `nodeSecurityGroup`
+    - `clusterIngressRuleId` instead of `clusterIngressRule`
+
+#### Cluster
+| New Top-Level Property | Type | Description | Default Value |
+|------------------------|------|-------------|---------------|
+| `clusterSecurityGroupId` | `Output<string>` | ID of the cluster security group | EKS-created security group ID |
+| `nodeSecurityGroupId` | `Output<string>` | ID of the node security group | EKS-created security group ID |
+| `clusterIngressRuleId` | `Output<string>` | ID of the cluster ingress rule. This is the rule that gives the nodes API server access | `""` |
+| `defaultNodeGroupAsgName` | `Output<string>` | Name of the default node group's auto scaling group | `""` |
+| `fargateProfileId` | `Output<string>` | ID of the Fargate profile if enabled | `""` |
+| `fargateProfileStatus` | `Output<string>` | Status of the Fargate profile if enabled | `""` |
+| `oidcProviderArn` | `Output<string>` | ARN of the OIDC provider if enabled | `""` |
+| `oidcProviderUrl` | `Output<string>` | URL of the OIDC provider | n/a |
+| `oidcIssuer` | `Output<string>` | URL of the OIDC provider without 'https://'. | n/a |
+
+#### NodeGroup & NodeGroupV2
+| New Top-Level Property | Type | Description | Default Value |
+|------------------------|------|-------------|---------------|
+| `nodeSecurityGroupId` | `Output<string>` | ID of the node security group | n/a |
+| `clusterIngressRuleId` |
+
 ## Miscellaneous changes
 
-### NodeGroup & NodeGroupV2 accept inputs for its properties
+### NodeGroup & NodeGroupV2 changes
+
+#### Input property types
 The `NodeGroup` and `NodeGroupV2` components now accept inputs for the following input properties:
 - `kubeletExtraArgs`
 - `bootstrapExtraArgs`
@@ -167,9 +200,14 @@ The `NodeGroup` and `NodeGroupV2` components now accept inputs for the following
 
 If you are using Go you will need to adjust your program to handle those types being inputs.
 
+#### Security group and ingress rule inputs
+We have updated the `NodeGroup` and `NodeGroupV2` components to allow passing in `nodeSecurityGroup` and `clusterIngressRule` by their IDs. You can now use `nodeSecurityGroupId` and `clusterIngressRuleId` as input properties.
+
+Because of this change, the `nodeSecurityGroup` output property is now optional. To work around this, we have added a required `nodeSecurityGroupId` output property you can use instead. Use `nodegroup.nodeSecurityGroupId` instead of `nodegroup.nodeSecurityGroup.id`.
+
 ### Default Security Groups can now be disabled
 If you do not need the default cluster and node security groups you can disable those now
-with the `skipDefaultSecurityGroups` flag. Those security groups will not be created when setting that flag to true.
+with the `skipDefaultSecurityGroups` flag. Those security groups will not be created when setting this flag to true.
 
 Because of this change, the `clusterSecurityGroup`, `nodeSecurityGroup` and `clusterIngressRule` properties are optional now. If you're using those outputs you'll need to update your code accordingly.