From 534887493a4f0860286978cbbe2d61f2556a502b Mon Sep 17 00:00:00 2001 From: Sean Yeh <109418+seanyeh@users.noreply.github.com> Date: Tue, 7 Jan 2025 12:37:12 -0600 Subject: [PATCH 1/2] Add developer setup instructions --- CONTRIBUTING.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ README.md | 38 +++++++++++++++++++++++++++++++++++--- 2 files changed, 81 insertions(+), 3 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b87aab0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,46 @@ +# Contributing to ESC SDK + +## Building from source + +### Prerequisites + +* [OpenAPI Generator](https://openapi-generator.tech/docs/installation/) + +### Building + +ESC SDK uses OpenAPI Generator to auto-generate the raw API clients from the `swagger.yaml` definition. + +To build the autogenerated API clients, run: + +```shell +make generate_sdks +``` + +Additionally, ESC SDK provides wrapper clients for TypeScript/JavaScript, Python, and Go. To build these packages, run: + +```shell +make build_typescript +make build_python +make build_go +``` + +## Submitting a Pull Request + +For contributors we use the [standard fork based workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962): Fork this repository, create a topic branch, and when ready, open a pull request from your fork. + +## Creating a Release + +This section is for Pulumi employees only. + +To release a new version of the provider, follow steps below: +- Create a release commit by updating `.version` and running `make generate_sdks` ([example](https://github.com/pulumi/esc-sdk/pull/61)) +- Run release commands, replacing `X.XX.XX` with your new version. + ``` + git checkout main + git pull + git tag sdk/vX.XX.XX + git tag vX.XX.XX + git push origin vX.XX.XX + git push origin sdk/vX.XX.XX + ``` +- Github Actions will automatically build, test and then publish the new release to all the various package managers diff --git a/README.md b/README.md index c82f504..7c128d2 100644 --- a/README.md +++ b/README.md @@ -2,19 +2,51 @@ Pulumi ESC (Environments, Secrets, and Configurations) provides a developer-first solution to simplify how you manage sensitive data and configurations across your entire application lifecycle. It's a fully managed solution allowing teams to generate dynamic cloud provider credentials, aggregate secrets, and configurations from multiple sources, and manage them through composable collections called "environments." These environments can be consumed from anywhere, making Pulumi ESC ideal for any application and development workflow. Additionally, while Pulumi ESC works independently to eliminate duplication and reduce drift and sprawl of secrets and configuration for all your applications, it also integrates smoothly with Pulumi Infrastructure as Code (IaC) to enhance these capabilities within the Pulumi ecosystem. -## Introducing the Pulumi ESC SDK +### Introducing the Pulumi ESC SDK We're excited to unveil the official Pulumi ESC SDK, making it even easier to harness the power of ESC directly within your applications using your favorite programming languages. The SDK provides a simple, programmatic interface to all of Pulumi ESC's robust features, allowing you to: Manage the Entire Lifecycle of Your Environments: Create new environments, list existing ones, and easily update or delete them as your needs evolve. You can even add version tags to your environments, making it simple to track changes and roll back to previous states if needed. Seamlessly Integrate Secrets and Configurations: Securely access and utilize secrets and configurations within your applications. The SDK provides a streamlined way to fetch the information you need, whether it's cloud credentials, database connection strings, feature flags, or any other sensitive data. -## Why use the Pulumi ESC SDK? +### Why use the Pulumi ESC SDK? Here's why you'll love using the Pulumi ESC SDK: * Focus on Building, Not Plumbing: No more writing boilerplate code for API interactions. The SDK handles the complexities of secret retrieval and configuration management, so you can focus on your application's core functionality. -* Eliminate Hardcoded Secrets: Say goodbye to hardcoded credentials scattered throughout your codebase. With the SDK, your application can securely retrieve secrets from Pulumi ESC at runtime. +* Eliminate Hardcoded Secrets: Say goodbye to hardcoded credentials scattered throughout your codebase. With the SDK, your application can securely retrieve secrets from Pulumi ESC at runtime. * Centralized Configuration Management: Manage all your application settings from a single source of truth. The SDK provides easy access to configurations stored in Pulumi ESC, ensuring consistency across environments. * Enhanced Security: The Pulumi ESC SDK promotes secure secret handling best practices. It handles the secure storage and retrieval of your sensitive data, minimizing the risk of accidental exposure. * Intuitive and Idiomatic: The SDK is built to feel like a natural extension of your chosen programming language. You'll work with familiar objects, methods, and patterns, making integration smooth and intuitive. * Type Safety and Code Completion: Benefit from the power of your IDE. The SDK provides type safety, enabling compile-time checks and helpful code suggestions that reduce errors and speed up your development workflow. + +## Getting Started + +### TypeScript/JavaScript + +```shell +npm install @pulumi/esc-sdk +``` + +[TypeScript/JavaScript examples](https://www.pulumi.com/docs/esc/development/languages-sdks/javascript/) + +### Python + +```shell +pip install pulumi-esc-sdk +``` + +[Python examples](https://www.pulumi.com/docs/esc/development/languages-sdks/python/) + +### Go + +```shell +go get github.com/pulumi/esc-sdk/sdk +``` + +[Go examples](https://www.pulumi.com/docs/esc/development/languages-sdks/go/) + +## API Reference Documentation + +* [TypeScript/JavaScript](https://www.pulumi.com/docs/reference/pkg/nodejs/pulumi/esc-sdk/) +* [Python](https://www.pulumi.com/docs/reference/pkg/python/pulumi_esc_sdk/) +* [Go](https://pkg.go.dev/github.com/pulumi/esc-sdk/sdk/go) From 03d48414e64ea1bc85221628ea727582a5c69991 Mon Sep 17 00:00:00 2001 From: Sean Yeh <109418+seanyeh@users.noreply.github.com> Date: Tue, 7 Jan 2025 15:17:07 -0600 Subject: [PATCH 2/2] Remove autogenerated python readme --- sdk/python/README.md | 155 ------------------------------------------- 1 file changed, 155 deletions(-) delete mode 100644 sdk/python/README.md diff --git a/sdk/python/README.md b/sdk/python/README.md deleted file mode 100644 index fc8617b..0000000 --- a/sdk/python/README.md +++ /dev/null @@ -1,155 +0,0 @@ -# esc -Pulumi ESC allows you to compose and manage hierarchical collections of configuration and secrets and consume them in various ways. - -This Python package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project: - -- API version: 0.1.0 -- Package version: 1.0.0 -- Generator version: 7.4.0 -- Build package: org.openapitools.codegen.languages.PythonClientCodegen - -## Requirements. - -Python 3.7+ - -## Installation & Usage -### pip install - -If the python package is hosted on a repository, you can install directly using: - -```sh -pip install git+https://github.com/pulumi/esc.git -``` -(you may need to run `pip` with root permission: `sudo pip install git+https://github.com/pulumi/esc.git`) - -Then import the package: -```python -import esc -``` - -### Setuptools - -Install via [Setuptools](http://pypi.python.org/pypi/setuptools). - -```sh -python setup.py install --user -``` -(or `sudo python setup.py install` to install the package for all users) - -Then import the package: -```python -import esc -``` - -### Tests - -Execute `pytest` to run the tests. - -## Getting Started - -Please follow the [installation procedure](#installation--usage) and then run the following: - -```python - -import esc -from esc.rest import ApiException -from pprint import pprint - -# Defining the host is optional and defaults to https://api.pulumi.com/api/preview -# See configuration.py for a list of all supported configuration parameters. -configuration = esc.Configuration( - host = "https://api.pulumi.com/api/preview" -) - -# The client must configure the authentication and authorization parameters -# in accordance with the API server security policy. -# Examples for each auth method are provided below, use the example that -# satisfies your auth use case. - -# Configure API key authorization: Authorization -configuration.api_key['Authorization'] = os.environ["API_KEY"] - -# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed -# configuration.api_key_prefix['Authorization'] = 'Bearer' - - -# Enter a context with an instance of the API client -with esc.ApiClient(configuration) as api_client: - # Create an instance of the API class - api_instance = esc.EscApi(api_client) - org_name = 'org_name_example' # str | Organization name - body = 'body_example' # str | Environment Yaml content - - try: - # Checks an environment definition for errors - api_response = api_instance.check_environment_yaml(org_name, body) - print("The response of EscApi->check_environment_yaml:\n") - pprint(api_response) - except ApiException as e: - print("Exception when calling EscApi->check_environment_yaml: %s\n" % e) - -``` - -## Documentation for API Endpoints - -All URIs are relative to *https://api.pulumi.com/api/preview* - -Class | Method | HTTP request | Description ------------- | ------------- | ------------- | ------------- -*EscApi* | [**check_environment_yaml**](docs/EscApi.md#check_environment_yaml) | **POST** /environments/{orgName}/yaml/check | Checks an environment definition for errors -*EscApi* | [**create_environment**](docs/EscApi.md#create_environment) | **POST** /environments/{orgName}/{envName} | Create a new environment -*EscApi* | [**decrypt_environment**](docs/EscApi.md#decrypt_environment) | **GET** /environments/{orgName}/{envName}/decrypt | Reads the definition for the given environment with static secrets in plaintext -*EscApi* | [**delete_environment**](docs/EscApi.md#delete_environment) | **DELETE** /environments/{orgName}/{envName} | Delete an environment -*EscApi* | [**get_environment**](docs/EscApi.md#get_environment) | **GET** /environments/{orgName}/{envName} | Read an environment -*EscApi* | [**get_environment_e_tag**](docs/EscApi.md#get_environment_e_tag) | **HEAD** /environments/{orgName}/{envName} | Return an Environment ETag -*EscApi* | [**list_environments**](docs/EscApi.md#list_environments) | **GET** /environments/{orgName} | List environments in the organization -*EscApi* | [**open_environment**](docs/EscApi.md#open_environment) | **POST** /environments/{orgName}/{envName}/open | Open an environment session -*EscApi* | [**read_open_environment**](docs/EscApi.md#read_open_environment) | **GET** /environments/{orgName}/{envName}/open/{openSessionID} | Read an open environment -*EscApi* | [**read_open_environment_property**](docs/EscApi.md#read_open_environment_property) | **GET** /environments/{orgName}/{envName}/open//{openSessionID} | Read an open environment -*EscApi* | [**update_environment_yaml**](docs/EscApi.md#update_environment_yaml) | **PATCH** /environments/{orgName}/{envName} | Update an existing environment with Yaml file - - -## Documentation For Models - - - [Access](docs/Access.md) - - [Accessor](docs/Accessor.md) - - [CheckEnvironment](docs/CheckEnvironment.md) - - [Environment](docs/Environment.md) - - [EnvironmentDefinition](docs/EnvironmentDefinition.md) - - [EnvironmentDefinitionValues](docs/EnvironmentDefinitionValues.md) - - [EnvironmentDiagnostic](docs/EnvironmentDiagnostic.md) - - [EnvironmentDiagnostics](docs/EnvironmentDiagnostics.md) - - [Error](docs/Error.md) - - [EvaluatedExecutionContext](docs/EvaluatedExecutionContext.md) - - [Expr](docs/Expr.md) - - [ExprBuiltin](docs/ExprBuiltin.md) - - [Interpolation](docs/Interpolation.md) - - [OpenEnvironment](docs/OpenEnvironment.md) - - [OrgEnvironment](docs/OrgEnvironment.md) - - [OrgEnvironments](docs/OrgEnvironments.md) - - [Pos](docs/Pos.md) - - [PropertyAccessor](docs/PropertyAccessor.md) - - [Range](docs/Range.md) - - [Reference](docs/Reference.md) - - [Trace](docs/Trace.md) - - [Value](docs/Value.md) - - - -## Documentation For Authorization - - -Authentication schemes defined for the API: - -### Authorization - -- **Type**: API key -- **API key parameter name**: Authorization -- **Location**: HTTP header - - -## Author - - - -