-
Notifications
You must be signed in to change notification settings - Fork 4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat(cli-plugin-contract): introduce a public contract between CLI and plugins #32111
base: main
Are you sure you want to change the base?
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The pull request linter has failed. See the aws-cdk-automation comment below for failure reasons. If you believe this pull request should receive an exemption, please comment and provide a justification.
A comment requesting an exemption should contain the text Exemption Request
. Additionally, if clarification is needed add Clarification Request
to a comment.
Codecov ReportAttention: Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #32111 +/- ##
==========================================
+ Coverage 77.17% 77.48% +0.30%
==========================================
Files 105 104 -1
Lines 7169 7164 -5
Branches 1315 1313 -2
==========================================
+ Hits 5533 5551 +18
+ Misses 1455 1431 -24
- Partials 181 182 +1
Flags with carried forward coverage won't be shown. Click here to find out more.
|
* | ||
* Guaranteed to be called only if canProvideCredentails() returned true at some point. | ||
*/ | ||
getProvider(accountId: string, mode: Mode): Promise<AwsCredentials>; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We change this to a strongly typed string, we can make this package types only.
getProvider(accountId: string, mode: Mode): Promise<AwsCredentials>; | |
getProvider(accountId: string, mode: 'ForReading' | 'ForWriting'): Promise<AwsCredentials>; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This would be a breaking change for plugins, which are expecting a number (ForReading
= 0, ForWriting
= 1).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
getProvider(accountId: string, mode: 0 | 1): Promise<AwsCredentials>;
getProviderEx(accountId: string, mode: 'ForReading' | 'ForWriting'): Promise<AwsCredentials>;
?
This reverts commit 16d3d4d.
/** | ||
* A list of credential provider sources | ||
*/ | ||
export interface CredentialProviderSourceRepository { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd happily rename this interface if someone has a better suggestion.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
PluginHost
?
It's technically also for lookup plugins, for example.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If we call it PluginHost
, what should we call the class that implements it in the CLI?
getPromise?: () => Promise<void>; | ||
} | ||
|
||
export enum Mode { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've considered making this a const enum
but, given the documented pitfalls, I've decided against it. This value will probably be used only once during the execution of the plugin, which itself is part of much bigger CDK command execution. So the cost of additional indirection when accessing enum values is negligible.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The goal of that was more to avoid having plugins take a runtime dependency on this package. They should be able to take only a devDependency
on this package.
What is the concrete pitfall you're concerned about?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
All three of them. If you look at the approaches to avoid them, they boil down to "do not use this feature if an external package is going to consume this enum", which is exactly the case here.
➡️ PR build request submitted to A maintainer must now check the pipeline and add the |
/** | ||
* A list of credential provider sources | ||
*/ | ||
export interface CredentialProviderSourceRepository { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
PluginHost
?
It's technically also for lookup plugins, for example.
* Refreshes the current credentials. This function only exists for | ||
* legacy reasons, to be compatible with the `AWS.Credentials` class. | ||
* Plugins that use the AWS SDK v3 don't need this. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not necessarily true. If you want credentials that need to refresh themselves (session credentials, for example), how else would they work?
/** | ||
* A Date when the identity or credential will no longer be accepted. | ||
*/ | ||
readonly expiration?: Date; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this actually used?
/** | ||
* AWS accountId. | ||
*/ | ||
readonly accountId?: string; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this actually used?
/** | ||
* AWS credential scope for this set of credentials. | ||
*/ | ||
readonly credentialScope?: string; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this actually used?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not directly by the CLI, but can be used by the SDK.
getPromise?: () => Promise<void>; | ||
} | ||
|
||
export enum Mode { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The goal of that was more to avoid having plugins take a runtime dependency on this package. They should be able to take only a devDependency
on this package.
What is the concrete pitfall you're concerned about?
@@ -65,13 +66,13 @@ export class CredentialPlugins { | |||
// Otherwise it must have returned credentials. | |||
const credentials = (providerOrCreds as any).resolvePromise |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The as any
should no longer be necessary, should it?
I don't see resolvePromise()
in the typing package. Where is it coming from? What is this object?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
True. It should be part of the interface.
packages/aws-cdk/package.json
Outdated
@@ -102,6 +102,7 @@ | |||
"xml-js": "^1.6.11" | |||
}, | |||
"dependencies": { | |||
"@aws-cdk/cli-plugin-contract": "0.0.0", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
devDependency
please
"peerDependencies": { | ||
"@aws-cdk/cli-plugin-contract": "0.0.0" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
dependency
+ peerDependency
together doesn't mean anything
The pull request linter fails with the following errors:
PRs must pass status checks before we can provide a meaningful review. If you would like to request an exemption from the status checks or clarification on feedback, please leave a comment on this PR containing |
AWS CodeBuild CI Report
Powered by github-codebuild-logs, available on the AWS Serverless Application Repository |
The CLI immediately invokes credential *providers* to produce *credentials*, and passes the credentials around instead of the providers. This means that if short-lived credentials expire (like session credentials from roles), there is no way to refresh them. CLI calls will start to fail if that happens. To fix this, instead of resolving providers to credentials, pass providers around instead. Implications for auth plugins ------------- This widens the plugin protocol: the new plugin protocol *forced* a translation to V3 credentials, and had no way to return V3 providers. While it is now possible to return V3 Credential Providers from the plugin protocol, plugin writers cannot easily take advantage of that protocol because there have been ~8 CLI releases that only support V3 credentials and will fail at runtime of V3 providers are returned. To support this, pass a new options argument into `getProvider()`: this will indicate whether V3 Providers are supported or not. Plugins can return a provider if the CLI indicates that it supports V3 providers, and avoid doing that if the CLI indicates it won't. That way, plugins can be rewritten to take advantage of returning V3 providers without crashing on CLI versions `2.167.0..(this releases)`. This also affects #32111 in which the plugin contract is being moved.
The CLI immediately invokes credential *providers* to produce *credentials*, and passes the credentials around instead of the providers. This means that if short-lived credentials expire (like session credentials from roles), there is no way to refresh them. CLI calls will start to fail if that happens. To fix this, instead of resolving providers to credentials, pass providers around instead. Implications for auth plugins ------------- This widens the plugin protocol: the new plugin protocol *forced* a translation to V3 credentials, and had no way to return V3 providers. While it is now possible to return V3 Credential Providers from the plugin protocol, plugin writers cannot easily take advantage of that protocol because there have been ~8 CLI releases that only support V3 credentials and will fail at runtime of V3 providers are returned. To support this, pass a new options argument into `getProvider()`: this will indicate whether V3 Providers are supported or not. Plugins can return a provider if the CLI indicates that it supports V3 providers, and avoid doing that if the CLI indicates it won't. That way, plugins can be rewritten to take advantage of returning V3 providers without crashing on CLI versions `2.167.0..(this releases)`. This also affects #32111 in which the plugin contract is being moved. Closes #32287. ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
The contract between the CLI and credential provider plugins is not publicly defined.
Extract the types involved in the CLI-plugin communication into a new package,
@aws-cdk/cli-plugin-contract
, and update all references in the CLI code.Closes #32099.
Checklist
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license