portfolios

Creates, updates, deletes, gets or lists a portfolios resource.

Overview

Name	portfolios
Type	Resource
Id	aws.servicecatalog.portfolios

Fields

The following fields are returned by SELECT queries:

describe_portfolio

Name	Datatype	Description
budgets	array	Information about the associated budgets.
portfolio_detail	object	Information about the portfolio.
tag_options	array	Information about the TagOptions associated with the portfolio.
tags	array	Information about the tags associated with the portfolio.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_portfolio	select	region		Gets information about the specified portfolio. A delegated admin is authorized to invoke this command.
create_portfolio	insert	region, DisplayName, ProviderName, IdempotencyToken		Creates a portfolio. A delegated admin is authorized to invoke this command.
associate_principal_with_portfolio	update	region, PortfolioId, PrincipalARN, PrincipalType		Associates the specified principal ARN with the specified portfolio. If you share the portfolio with principal name sharing enabled, the PrincipalARN association is included in the share. The PortfolioID, PrincipalARN, and PrincipalType parameters are required. You can associate a maximum of 10 Principals with a portfolio using PrincipalType as IAM_PATTERN. When you associate a principal with portfolio, a potential privilege escalation path may occur when that portfolio is then shared with other accounts. For a user in a recipient account who is not an Service Catalog Admin, but still has the ability to create Principals (Users/Groups/Roles), that user could create a role that matches a principal name association for the portfolio. Although this user may not know which principal names are associated through Service Catalog, they may be able to guess the user. If this potential escalation path is a concern, then Service Catalog recommends using PrincipalType as IAM. With this configuration, the PrincipalARN must already exist in the recipient account before it can be associated.
associate_product_with_portfolio	update	region, ProductId, PortfolioId		Associates the specified product with the specified portfolio. A delegated admin is authorized to invoke this command.
disassociate_principal_from_portfolio	update	region, PortfolioId, PrincipalARN		Disassociates a previously associated principal ARN from a specified portfolio. The PrincipalType and PrincipalARN must match the AssociatePrincipalWithPortfolio call request details. For example, to disassociate an association created with a PrincipalARN of PrincipalType IAM you must use the PrincipalType IAM when calling DisassociatePrincipalFromPortfolio. For portfolios that have been shared with principal name sharing enabled: after disassociating a principal, share recipient accounts will no longer be able to provision products in this portfolio using a role matching the name of the associated principal. For more information, review associate-principal-with-portfolio in the Amazon Web Services CLI Command Reference. If you disassociate a principal from a portfolio, with PrincipalType as IAM, the same principal will still have access to the portfolio if it matches one of the associated principals of type IAM_PATTERN. To fully remove access for a principal, verify all the associated Principals of type IAM_PATTERN, and then ensure you disassociate any IAM_PATTERN principals that match the principal whose access you are removing.
update_portfolio	update	region		Updates the specified portfolio. You cannot update a product that was shared with you.
delete_portfolio	delete	region		Deletes the specified portfolio. You cannot delete a portfolio if it was shared with you or if it has associated products, users, constraints, or shared accounts. A delegated admin is authorized to invoke this command.
accept_portfolio_share	exec	region, PortfolioId		Accepts an offer to share the specified portfolio.
disassociate_product_from_portfolio	exec	region, ProductId, PortfolioId		Disassociates the specified product from the specified portfolio. A delegated admin is authorized to invoke this command.
list_portfolios	exec	region		Lists all portfolios in the catalog.
reject_portfolio_share	exec	region, PortfolioId		Rejects an offer to share the specified portfolio.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

describe_portfolio

Gets information about the specified portfolio. A delegated admin is authorized to invoke this command.

SELECT
budgets,
portfolio_detail,
tag_options,
tags
FROM aws.servicecatalog.portfolios
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_portfolio

Creates a portfolio. A delegated admin is authorized to invoke this command.

INSERT INTO aws.servicecatalog.portfolios (
AcceptLanguage,
DisplayName,
Description,
ProviderName,
Tags,
IdempotencyToken,
region
)
SELECT 
'{{ AcceptLanguage }}',
'{{ DisplayName }}' /* required */,
'{{ Description }}',
'{{ ProviderName }}' /* required */,
'{{ Tags }}',
'{{ IdempotencyToken }}' /* required */,
'{{ region }}'
RETURNING
portfolio_detail,
tags
;

Manifest

# Description fields are for documentation purposes
- name: portfolios
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the portfolios resource.
  - name: AcceptLanguage
    value: "{{ AcceptLanguage }}"
    description: |
      The language code. jp - Japanese zh - Chinese
  - name: DisplayName
    value: "{{ DisplayName }}"
    description: |
      The name to use for display purposes.
  - name: Description
    value: "{{ Description }}"
    description: |
      The description of the portfolio.
  - name: ProviderName
    value: "{{ ProviderName }}"
    description: |
      The name of the portfolio provider.
  - name: Tags
    description: |
      One or more tags.
    value:
      - Key: "{{ Key }}"
        Value: "{{ Value }}"
  - name: IdempotencyToken
    value: "{{ IdempotencyToken }}"
    description: |
      A unique identifier that you provide to ensure idempotency. If multiple requests differ only by the idempotency token, the same response is returned for each repeated request.

UPDATE examples

associate_principal_with_portfolio

Associates the specified principal ARN with the specified portfolio. If you share the portfolio with principal name sharing enabled, the PrincipalARN association is included in the share. The PortfolioID, PrincipalARN, and PrincipalType parameters are required. You can associate a maximum of 10 Principals with a portfolio using PrincipalType as IAM_PATTERN. When you associate a principal with portfolio, a potential privilege escalation path may occur when that portfolio is then shared with other accounts. For a user in a recipient account who is not an Service Catalog Admin, but still has the ability to create Principals (Users/Groups/Roles), that user could create a role that matches a principal name association for the portfolio. Although this user may not know which principal names are associated through Service Catalog, they may be able to guess the user. If this potential escalation path is a concern, then Service Catalog recommends using PrincipalType as IAM. With this configuration, the PrincipalARN must already exist in the recipient account before it can be associated.

UPDATE aws.servicecatalog.portfolios
SET 
AcceptLanguage = '{{ AcceptLanguage }}',
PortfolioId = '{{ PortfolioId }}',
PrincipalARN = '{{ PrincipalARN }}',
PrincipalType = '{{ PrincipalType }}'
WHERE 
region = '{{ region }}' --required
AND PortfolioId = '{{ PortfolioId }}' --required
AND PrincipalARN = '{{ PrincipalARN }}' --required
AND PrincipalType = '{{ PrincipalType }}' --required;

associate_product_with_portfolio

Associates the specified product with the specified portfolio. A delegated admin is authorized to invoke this command.

UPDATE aws.servicecatalog.portfolios
SET 
AcceptLanguage = '{{ AcceptLanguage }}',
ProductId = '{{ ProductId }}',
PortfolioId = '{{ PortfolioId }}',
SourcePortfolioId = '{{ SourcePortfolioId }}'
WHERE 
region = '{{ region }}' --required
AND ProductId = '{{ ProductId }}' --required
AND PortfolioId = '{{ PortfolioId }}' --required;

disassociate_principal_from_portfolio

Disassociates a previously associated principal ARN from a specified portfolio. The PrincipalType and PrincipalARN must match the AssociatePrincipalWithPortfolio call request details. For example, to disassociate an association created with a PrincipalARN of PrincipalType IAM you must use the PrincipalType IAM when calling DisassociatePrincipalFromPortfolio. For portfolios that have been shared with principal name sharing enabled: after disassociating a principal, share recipient accounts will no longer be able to provision products in this portfolio using a role matching the name of the associated principal. For more information, review associate-principal-with-portfolio in the Amazon Web Services CLI Command Reference. If you disassociate a principal from a portfolio, with PrincipalType as IAM, the same principal will still have access to the portfolio if it matches one of the associated principals of type IAM_PATTERN. To fully remove access for a principal, verify all the associated Principals of type IAM_PATTERN, and then ensure you disassociate any IAM_PATTERN principals that match the principal whose access you are removing.

UPDATE aws.servicecatalog.portfolios
SET 
AcceptLanguage = '{{ AcceptLanguage }}',
PortfolioId = '{{ PortfolioId }}',
PrincipalARN = '{{ PrincipalARN }}',
PrincipalType = '{{ PrincipalType }}'
WHERE 
region = '{{ region }}' --required
AND PortfolioId = '{{ PortfolioId }}' --required
AND PrincipalARN = '{{ PrincipalARN }}' --required;

update_portfolio

Updates the specified portfolio. You cannot update a product that was shared with you.

UPDATE aws.servicecatalog.portfolios
SET 
AcceptLanguage = '{{ AcceptLanguage }}',
Id = '{{ Id }}',
DisplayName = '{{ DisplayName }}',
Description = '{{ Description }}',
ProviderName = '{{ ProviderName }}',
AddTags = '{{ AddTags }}',
RemoveTags = '{{ RemoveTags }}'
WHERE 
region = '{{ region }}' --required
RETURNING
portfolio_detail,
tags;

DELETE examples

delete_portfolio

Deletes the specified portfolio. You cannot delete a portfolio if it was shared with you or if it has associated products, users, constraints, or shared accounts. A delegated admin is authorized to invoke this command.

DELETE FROM aws.servicecatalog.portfolios
WHERE region = '{{ region }}' --required
;

Lifecycle Methods

accept_portfolio_share

Accepts an offer to share the specified portfolio.

EXEC aws.servicecatalog.portfolios.accept_portfolio_share 
@region='{{ region }}' --required 
@@json=
'{
"AcceptLanguage": "{{ AcceptLanguage }}", 
"PortfolioId": "{{ PortfolioId }}", 
"PortfolioShareType": "{{ PortfolioShareType }}"
}'
;

disassociate_product_from_portfolio

Disassociates the specified product from the specified portfolio. A delegated admin is authorized to invoke this command.

EXEC aws.servicecatalog.portfolios.disassociate_product_from_portfolio 
@region='{{ region }}' --required 
@@json=
'{
"AcceptLanguage": "{{ AcceptLanguage }}", 
"ProductId": "{{ ProductId }}", 
"PortfolioId": "{{ PortfolioId }}"
}'
;

list_portfolios

Lists all portfolios in the catalog.

EXEC aws.servicecatalog.portfolios.list_portfolios 
@region='{{ region }}' --required 
@@json=
'{
"AcceptLanguage": "{{ AcceptLanguage }}", 
"PageToken": "{{ PageToken }}", 
"PageSize": {{ PageSize }}
}'
;

reject_portfolio_share

Rejects an offer to share the specified portfolio.

EXEC aws.servicecatalog.portfolios.reject_portfolio_share 
@region='{{ region }}' --required 
@@json=
'{
"AcceptLanguage": "{{ AcceptLanguage }}", 
"PortfolioId": "{{ PortfolioId }}", 
"PortfolioShareType": "{{ PortfolioShareType }}"
}'
;