From 5a88a2c60ec23377d97785347ccf5b154886bc59 Mon Sep 17 00:00:00 2001 From: Reshma Abdul Rahim Date: Fri, 14 Jun 2024 12:59:03 -0400 Subject: [PATCH 001/118] Add product doc for UDT Signed-off-by: Reshma Abdul Rahim --- ...-06-resource-extensibility-product-spec.md | 133 ++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 resources/2023-06-resource-extensibility-product-spec.md diff --git a/resources/2023-06-resource-extensibility-product-spec.md b/resources/2023-06-resource-extensibility-product-spec.md new file mode 100644 index 00000000..3afe0c8a --- /dev/null +++ b/resources/2023-06-resource-extensibility-product-spec.md @@ -0,0 +1,133 @@ +# Resource Extensibility (User Defined Resource Types) + +## Summary +The cloud native landscape is changing and expanding at a rapid pace like never before. Many enterprises use a wide range of technologies together for achieving their cloud-native strategy. For any technology that’s a newcomer and helps solve a problem in the cloud native landscape, users look for an easy and seamless way to integrate their existing tools and technologies and incrementally adopt the new technology to their strategy. For Radius, we have heard requests from our customers/community to support technologies that their applications are tightly coupled with E.g.: an internal messaging service or a technology they absolutely love E.g.: PostgreSQL/Kafka. + +We need to enable the open-source community to build and experiment with imperfect things. We need to provide an extensibility model that supports “Bring your own technology”, define and use it with Radius. This will help us to meet the community where they are and enable them to experiment and leverage their work as open-source contributions. + +One of the high value extensibility points in Radius is Recipes. We have received interests to create custom resource types, define Recipes for the custom resource types and use it in the Radius application. Today Radius Extenders helps in creating custom resource types, but they are untyped and have limitations. The goal of providing resource extensibility is to empower developers or infrastructure operators to author and run their applications with custom resource types seamlessly in Radius and use all the other features such as Recipes, connections and app graph with ease and flexibility. + +### Top level goals +1. Enable users to author their applications with custom resource types in Radius without having to write Go code to integrate with Radius components and deploy their application seamlessly. +2. Automatically enable Radius features such as Recipes, Connections, App graph, rad CLI for custom resource types. +3. Enable users to contribute and open-source the custom resource types to the community. +4. Radius uses the resource extensibility for its already built in resource types + +### Non-goals (out of scope) + + + +## Customer profile and challenges +**Enterprises**: Platform engineering teams or operations in enterprises focus on streamlining the developer-experience for their organization by defining a set of recommended practices for application teams and provide self-service capabilities for application teams/developers to use. Radius aids the platform engineering efforts with the help of Recipes where the platform engineers or operators define the infrastructure-as-code templates to create resources on demand when application is deployed. One of the major challenges that exists with the Recipes today is the limited number of resources supported. Radius doesn’t provide an extensibility model for users to bring their custom resources, define Recipes and deploy them. + +**Open-source community**: Building a sustainable open-source community is crucial to the success of any open-source project, including Radius. We need to cultivate an ecosystem for the open-source community to thrive, innovate and produce high quality work. Users from the community are motivated to contribute for different reasons: + - They want to use the project at their work and need a feature, + - The project triggered their interests in the cloud native landscape + - They want to code in a particular language E.g. :Go + +Today Radius enables users to get started on contributing to Radius with good-first-issues but doesn’t have a model to promote contributions further. Since the beginning of its open source launch, Dapr created the components repository and invited users to build their own components to unblock their scenarios and in turn folks contributed to the project. Learning from Dapr, Radius needs to have the extensibility points defined for contributors to interact with the project so that they can build out the things that they need to enable their scenarios and in turn the community gets benefitted with those contributions. + +### Customer persona(s) + +- Platform engineers: Platform engineers are responsible for streamlining the developer-experience for their organization by defining a set of recommended practices for application teams and provide self-service capabilities for application teams/developers to use. They are responsible for defining the infrastructure-as-code templates for the application and are the primary users of Recipes. + +- System Reliability Engineers (SREs) : SREs are responsible for ensuring the reliability of the applications and services that are deployed in the cloud. They are responsible for maintaining the infrastructure and ensuring that the applications are running smoothly. They maintain the infrastructure-as-code templates and provide support for the applications that are deployed. + +- System integrators : System integrators are partners who help enterprises integrate proprietary services with cloud native applications. They are responsible for designing and building cloud native applications on behalf of their customers. + +- Developers : Developers are responsible for building the cloud native applications. They are responsible for writing the code, designing and maintaining the applications. + +- Open-source contributors : Cloud native open-source contributors are developers who are interested in contributing to the cloud native projects. They are responsible for building the cloud native projects and contributing to the open-source projects. They can be any of the above personas who are interested in contributing to the cloud native projects. + +### Positive customer outcomes +- Author and deploy : I can bring my own applications with custom resources/services and integrate with Radius seamlessly. I don’t have to write Go code to integrate with Radius components and can use simple spec to generate the resource definition and integrate with Radius + +- Recipes for user defined types: I can create Recipes for the custom resource types and deploy via Radius + +- OSS contributions: I can create and contribute Recipes for the custom resource types for the community to use. + +## Key scenarios + +### Scenario 1: Deb integrates the Budgets app with Radius +Deb, a platform engineer at a Financial Services company, wants to integrate the Budgets app with Radius. The Budgets app relies on an internal messaging service called Plaid. Deb wants to use Plaid as a resource type in Radius to deploy the application seamlessly. He needs a way to define and use Plaid as a custom resource type in Radius without having to write Go code. This will enable him to leverage all the features of Radius, such as Recipes, Connections, and the rad CLI, with ease and flexibility. + +### Scenario 2: Amy contributes and open-sources PostgreSQL support to Radius +Amy is a system integrator who helps customers build cloud native applications on AWS. Amy heard about Radius and starts integrating their customer workloads in Radius. She sees a lot of her scenarios involve PostgreSQL and finds Radius doesn’t support that yet. She wants to contribute the PostgreSQL support to Radius and open source it so anyone can use it + +### Scenario 3: Raj publishes Recipes for proprietary services +Raj is a partner or a system integrator who helps enterprises integrate proprietary service for eg : Oracle database in their cloud native applications. Raj tries out Radius and wants to write Recipes to create an Oracle Database with a standard set of best practices and policies integrated. He works with a lot of customers who are wanting to use the Oracle Database recipe in their applications. + +## Key dependencies and risks + + + + + + +- Dependency: Bicep compiler merge support + - We need to ensure that the ongoing Bicep compiler merge work is complete so that custom resource types can be dynamically generated for the user defined resource types. + - Mitigation: Work closely with the Bicep team to ensure that the merge is completed on time and that the necessary features are available to enable custom resource types in Radius . + +- Risk: Adoption and community engagement + - There is a risk that users may not fully embrace the extensibility feature or contribute custom resource types to the community. + - Mitigation: Actively engage with users, provide clear documentation and resources, and foster a supportive and inclusive community to encourage adoption and contributions. + +- Risk: Compatibility and maintainability + - As more custom resource types are added to Radius, there is a risk of compatibility issues and increased maintenance overhead. + - Mitigation: Implement thorough testing and versioning strategies to ensure compatibility, and establish clear guidelines for maintaining custom resource types. + +- Risk: Security and trust + - Allowing users to contribute custom resource types introduces potential security risks and the need to establish trust in the community-contributed code. + - Mitigation: Implement strict security measures, such as code reviews and vulnerability scanning, and establish a transparent review process for community contributions. + +## Key assumptions to test and questions to answer + + + +- Assumption: Users will find value in the extensibility feature and actively contribute to the community. + +## Current state + +[Radius Extenders](https://docs.radapp.io/guides/author-apps/custom/overview/#extenders) enables users to author custom resource types but they are weakly types. They allow you to pass in any property or secret and for cases where the developer/operator need to extend and reference a simple resource type definition. Extenders are for untyped/ weakly typed resources and do not provide a lot of customization for users wanting to have guardrails in their platforms with strongly typed resource definitions following a strict set of rules and restrictions. + +# Scenario: TODO + +## Target customers + + +## Existing customer problem + + +## Desired customer experience outcome + + +### Detailed Customer Experience + + + +## Key investments + + +### Feature 1 + + +### Feature 2 + + +### Feature 3 + + +## Key dependencies and risks + + + + + +## Key assumptions to test and questions to answer + + + +## Current state + \ No newline at end of file From f54764681acb407fca46b5bb640725ede6201e6c Mon Sep 17 00:00:00 2001 From: Reshma Abdul Rahim Date: Tue, 18 Jun 2024 14:13:29 -0400 Subject: [PATCH 002/118] Rename file Signed-off-by: Reshma Abdul Rahim --- ...-06-resource-extensibility-product-spec.md | 133 ++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 resources/2024-06-resource-extensibility-product-spec.md diff --git a/resources/2024-06-resource-extensibility-product-spec.md b/resources/2024-06-resource-extensibility-product-spec.md new file mode 100644 index 00000000..8a7da3a9 --- /dev/null +++ b/resources/2024-06-resource-extensibility-product-spec.md @@ -0,0 +1,133 @@ +# Resource Extensibility (User Defined Resource Types) + +## Summary +The cloud native landscape is changing and expanding at a rapid pace like never before. Many enterprises use a wide range of technologies together for achieving their cloud-native strategy. For any technology that’s a newcomer and helps solve a problem in the cloud native landscape, users look for an easy and seamless way to integrate their existing tools and technologies and incrementally adopt the new technology to their strategy. For Radius, we have heard requests from our customers/community to support technologies that their applications are tightly coupled with E.g.: an internal messaging service or a technology they absolutely love E.g.: PostgreSQL/Kafka. + +We need to enable the open-source community to build and experiment with imperfect things. We need to provide an extensibility model that supports “Bring your own technology”, define and use it with Radius. This will help us to meet the community where they are and enable them to experiment and leverage their work as open-source contributions. + +One of the high value extensibility points in Radius is Recipes. We have received interests to create custom resource types, define Recipes for the custom resource types and use it in the Radius application. Today Radius Extenders helps in creating custom resource types, but they are untyped and have limitations. The goal of providing resource extensibility is to empower developers or infrastructure operators to author and run their applications with custom resource types seamlessly in Radius and use all the other features such as Recipes, connections and app graph with ease and flexibility. + +### Top level goals +1. Enable users to author their applications with custom resource types in Radius without having to write Go code to integrate with Radius components and deploy their application seamlessly. +2. Automatically enable Radius features such as Recipes, Connections, App graph, rad CLI for custom resource types. +3. Enable users to contribute and open-source the custom resource types to the community. +4. Radius uses the resource extensibility for its already built in resource types + +### Non-goals (out of scope) + + + +## Customer profile and challenges +**Enterprises**: Platform engineering teams or operations in enterprises focus on streamlining the developer-experience for their organization by defining a set of recommended practices for application teams and provide self-service capabilities for application teams/developers to use. Radius aids the platform engineering efforts with the help of Recipes where the platform engineers or operators define the infrastructure-as-code templates to create resources on demand when application is deployed. One of the major challenges that exists with the Recipes today is the limited number of resources supported. Radius doesn’t provide an extensibility model for users to bring their custom resources, define Recipes and deploy them. + +**Open-source community**: Building a sustainable open-source community is crucial to the success of any open-source project, including Radius. We need to cultivate an ecosystem for the open-source community to thrive, innovate and produce high quality work. Users from the community are motivated to contribute for different reasons: + - They want to use the project at their work and need a feature, + - The project triggered their interests in the cloud native landscape + - They want to code in a particular language E.g. :Go + +Today Radius enables users to get started on contributing to Radius with good-first-issues but doesn’t have a model to promote contributions further. Since the beginning of its open source launch, Dapr created the components repository and invited users to build their own components to unblock their scenarios and in turn folks contributed to the project. Learning from Dapr, Radius needs to have the extensibility points defined for contributors to interact with the project so that they can build out the things that they need to enable their scenarios and in turn the community gets benefitted with those contributions. + +### Customer persona(s) + +- Platform engineers: Platform engineers are responsible for streamlining the developer-experience for their organization by defining a set of recommended practices for application teams and provide self-service capabilities for application teams/developers to use. They are responsible for building the platform and providing the necessary tools and services for the application teams to deploy their applications. + +- IT Operators: IT operators are responsible for managing the infrastructure and ensuring that the applications are running smoothly. They are responsible for maintaining the infrastructure and providing support for the infrastructure. They are the primary users of Radius Recipes as they are responsible for defining the infrastructure-as-code templates for the applications. + +- System Reliability Engineers (SREs) : SREs are responsible for ensuring the reliability of the applications and services that are deployed in the cloud. They are responsible for maintaining the infrastructure and ensuring that the applications are running smoothly. They maintain the infrastructure-as-code templates and provide support for the applications that are deployed. + +- System integrators : System integrators are partners who help enterprises integrate proprietary services with cloud native applications. They are responsible for designing and building cloud native applications on behalf of their customers. + +- Developers : Developers are responsible for building the cloud native applications. They are responsible for writing the code, designing and maintaining the applications. + +- Open-source contributors : Cloud native open-source contributors are developers who are interested in contributing to the cloud native projects. They are responsible for building the cloud native projects and contributing to the open-source projects. They can be any of the above personas who are interested in contributing to the cloud native projects. + +### Positive customer outcomes +- Author and deploy : I can bring my own applications with custom resources/services and integrate with Radius seamlessly. I don’t have to write Go code to integrate with Radius components and can use simple spec to generate the resource definition and integrate with Radius + +- Recipes for user defined types: I can create Recipes for the custom resource types and deploy via Radius + +- OSS contributions: I can create and contribute Recipes for the custom resource types for the community to use. + +## Key scenarios + +### Scenario 1: Deb integrates the Budgets app with Radius +Deb, a platform engineer at a Financial Services company, wants to integrate the Budgets app with Radius. The Budgets app relies on an internal messaging service called Plaid. Deb wants to use Plaid as a resource type in Radius to deploy the application seamlessly. He needs a way to define and use Plaid as a custom resource type in Radius without having to write Go code. This will enable him to leverage all the features of Radius, such as Recipes, Connections, and the rad CLI, with ease and flexibility. + +### Scenario 2: Amy contributes and open-sources PostgreSQL support to Radius +Amy is a system integrator who helps customers build cloud native applications on AWS. Amy heard about Radius and starts integrating their customer workloads in Radius. She sees a lot of her scenarios involve PostgreSQL and finds Radius doesn’t support that yet. She wants to contribute the PostgreSQL support to Radius and open source it so anyone can use it + +### Scenario 3: Raj publishes Recipes for proprietary services +Raj is a partner or a system integrator who helps enterprises integrate proprietary service for eg : Oracle database in their cloud native applications. Raj tries out Radius and wants to write Recipes to create an Oracle Database with a standard set of best practices and policies integrated. He works with a lot of customers who are wanting to use the Oracle Database recipe in their applications. + +## Key dependencies and risks + + + + + + +- Dependency: Bicep compiler merge support + - We need to ensure that the ongoing Bicep compiler merge work is complete so that custom resource types can be dynamically generated for the user defined resource types. + - Mitigation: Work closely with the Bicep team to ensure that the merge is completed on time and that the necessary features are available to enable custom resource types in Radius . + +- Risk: Adoption and community engagement + - There is a risk that users may not fully embrace the extensibility feature or contribute custom resource types to the community. + - Mitigation: Actively engage with users, provide clear documentation and resources, and foster a supportive and inclusive community to encourage adoption and contributions. + +- Risk: Compatibility and maintainability + - As more custom resource types are added to Radius, there is a risk of compatibility issues and increased maintenance overhead. + - Mitigation: Implement thorough testing and versioning strategies to ensure compatibility, and establish clear guidelines for maintaining custom resource types. + +- Risk: Security and trust + - Allowing users to contribute custom resource types introduces potential security risks and the need to establish trust in the community-contributed code. + - Mitigation: Implement strict security measures, such as code reviews and vulnerability scanning, and establish a transparent review process for community contributions. + +## Key assumptions to test and questions to answer + + + +- Assumption: Users will find value in the extensibility feature and actively contribute to the community. + +## Current state + +[Radius Extenders](https://docs.radapp.io/guides/author-apps/custom/overview/#extenders) enables users to author custom resource types but they are weakly types. They allow you to pass in any property or secret and for cases where the developer/operator need to extend and reference a simple resource type definition. Extenders are for untyped/ weakly typed resources and do not provide a lot of customization for users wanting to have guardrails in their platforms with strongly typed resource definitions following a strict set of rules and restrictions. + +## Target customers + + +## Existing customer problem + + +## Desired customer experience outcome + + +### Detailed Customer Experience + + + +## Key investments + + +### Feature 1 + + +### Feature 2 + + +### Feature 3 + + +## Key dependencies and risks + + + + + +## Key assumptions to test and questions to answer + + + +## Current state + \ No newline at end of file From 1a5b0f99e47c3e9ee40ac600159ed7380074d35e Mon Sep 17 00:00:00 2001 From: Reshma Abdul Rahim Date: Tue, 18 Jun 2024 14:28:49 -0400 Subject: [PATCH 003/118] Rename file Signed-off-by: Reshma Abdul Rahim --- ...-06-resource-extensibility-product-spec.md | 133 ------------------ 1 file changed, 133 deletions(-) delete mode 100644 resources/2023-06-resource-extensibility-product-spec.md diff --git a/resources/2023-06-resource-extensibility-product-spec.md b/resources/2023-06-resource-extensibility-product-spec.md deleted file mode 100644 index 3afe0c8a..00000000 --- a/resources/2023-06-resource-extensibility-product-spec.md +++ /dev/null @@ -1,133 +0,0 @@ -# Resource Extensibility (User Defined Resource Types) - -## Summary -The cloud native landscape is changing and expanding at a rapid pace like never before. Many enterprises use a wide range of technologies together for achieving their cloud-native strategy. For any technology that’s a newcomer and helps solve a problem in the cloud native landscape, users look for an easy and seamless way to integrate their existing tools and technologies and incrementally adopt the new technology to their strategy. For Radius, we have heard requests from our customers/community to support technologies that their applications are tightly coupled with E.g.: an internal messaging service or a technology they absolutely love E.g.: PostgreSQL/Kafka. - -We need to enable the open-source community to build and experiment with imperfect things. We need to provide an extensibility model that supports “Bring your own technology”, define and use it with Radius. This will help us to meet the community where they are and enable them to experiment and leverage their work as open-source contributions. - -One of the high value extensibility points in Radius is Recipes. We have received interests to create custom resource types, define Recipes for the custom resource types and use it in the Radius application. Today Radius Extenders helps in creating custom resource types, but they are untyped and have limitations. The goal of providing resource extensibility is to empower developers or infrastructure operators to author and run their applications with custom resource types seamlessly in Radius and use all the other features such as Recipes, connections and app graph with ease and flexibility. - -### Top level goals -1. Enable users to author their applications with custom resource types in Radius without having to write Go code to integrate with Radius components and deploy their application seamlessly. -2. Automatically enable Radius features such as Recipes, Connections, App graph, rad CLI for custom resource types. -3. Enable users to contribute and open-source the custom resource types to the community. -4. Radius uses the resource extensibility for its already built in resource types - -### Non-goals (out of scope) - - - -## Customer profile and challenges -**Enterprises**: Platform engineering teams or operations in enterprises focus on streamlining the developer-experience for their organization by defining a set of recommended practices for application teams and provide self-service capabilities for application teams/developers to use. Radius aids the platform engineering efforts with the help of Recipes where the platform engineers or operators define the infrastructure-as-code templates to create resources on demand when application is deployed. One of the major challenges that exists with the Recipes today is the limited number of resources supported. Radius doesn’t provide an extensibility model for users to bring their custom resources, define Recipes and deploy them. - -**Open-source community**: Building a sustainable open-source community is crucial to the success of any open-source project, including Radius. We need to cultivate an ecosystem for the open-source community to thrive, innovate and produce high quality work. Users from the community are motivated to contribute for different reasons: - - They want to use the project at their work and need a feature, - - The project triggered their interests in the cloud native landscape - - They want to code in a particular language E.g. :Go - -Today Radius enables users to get started on contributing to Radius with good-first-issues but doesn’t have a model to promote contributions further. Since the beginning of its open source launch, Dapr created the components repository and invited users to build their own components to unblock their scenarios and in turn folks contributed to the project. Learning from Dapr, Radius needs to have the extensibility points defined for contributors to interact with the project so that they can build out the things that they need to enable their scenarios and in turn the community gets benefitted with those contributions. - -### Customer persona(s) - -- Platform engineers: Platform engineers are responsible for streamlining the developer-experience for their organization by defining a set of recommended practices for application teams and provide self-service capabilities for application teams/developers to use. They are responsible for defining the infrastructure-as-code templates for the application and are the primary users of Recipes. - -- System Reliability Engineers (SREs) : SREs are responsible for ensuring the reliability of the applications and services that are deployed in the cloud. They are responsible for maintaining the infrastructure and ensuring that the applications are running smoothly. They maintain the infrastructure-as-code templates and provide support for the applications that are deployed. - -- System integrators : System integrators are partners who help enterprises integrate proprietary services with cloud native applications. They are responsible for designing and building cloud native applications on behalf of their customers. - -- Developers : Developers are responsible for building the cloud native applications. They are responsible for writing the code, designing and maintaining the applications. - -- Open-source contributors : Cloud native open-source contributors are developers who are interested in contributing to the cloud native projects. They are responsible for building the cloud native projects and contributing to the open-source projects. They can be any of the above personas who are interested in contributing to the cloud native projects. - -### Positive customer outcomes -- Author and deploy : I can bring my own applications with custom resources/services and integrate with Radius seamlessly. I don’t have to write Go code to integrate with Radius components and can use simple spec to generate the resource definition and integrate with Radius - -- Recipes for user defined types: I can create Recipes for the custom resource types and deploy via Radius - -- OSS contributions: I can create and contribute Recipes for the custom resource types for the community to use. - -## Key scenarios - -### Scenario 1: Deb integrates the Budgets app with Radius -Deb, a platform engineer at a Financial Services company, wants to integrate the Budgets app with Radius. The Budgets app relies on an internal messaging service called Plaid. Deb wants to use Plaid as a resource type in Radius to deploy the application seamlessly. He needs a way to define and use Plaid as a custom resource type in Radius without having to write Go code. This will enable him to leverage all the features of Radius, such as Recipes, Connections, and the rad CLI, with ease and flexibility. - -### Scenario 2: Amy contributes and open-sources PostgreSQL support to Radius -Amy is a system integrator who helps customers build cloud native applications on AWS. Amy heard about Radius and starts integrating their customer workloads in Radius. She sees a lot of her scenarios involve PostgreSQL and finds Radius doesn’t support that yet. She wants to contribute the PostgreSQL support to Radius and open source it so anyone can use it - -### Scenario 3: Raj publishes Recipes for proprietary services -Raj is a partner or a system integrator who helps enterprises integrate proprietary service for eg : Oracle database in their cloud native applications. Raj tries out Radius and wants to write Recipes to create an Oracle Database with a standard set of best practices and policies integrated. He works with a lot of customers who are wanting to use the Oracle Database recipe in their applications. - -## Key dependencies and risks - - - - - - -- Dependency: Bicep compiler merge support - - We need to ensure that the ongoing Bicep compiler merge work is complete so that custom resource types can be dynamically generated for the user defined resource types. - - Mitigation: Work closely with the Bicep team to ensure that the merge is completed on time and that the necessary features are available to enable custom resource types in Radius . - -- Risk: Adoption and community engagement - - There is a risk that users may not fully embrace the extensibility feature or contribute custom resource types to the community. - - Mitigation: Actively engage with users, provide clear documentation and resources, and foster a supportive and inclusive community to encourage adoption and contributions. - -- Risk: Compatibility and maintainability - - As more custom resource types are added to Radius, there is a risk of compatibility issues and increased maintenance overhead. - - Mitigation: Implement thorough testing and versioning strategies to ensure compatibility, and establish clear guidelines for maintaining custom resource types. - -- Risk: Security and trust - - Allowing users to contribute custom resource types introduces potential security risks and the need to establish trust in the community-contributed code. - - Mitigation: Implement strict security measures, such as code reviews and vulnerability scanning, and establish a transparent review process for community contributions. - -## Key assumptions to test and questions to answer - - - -- Assumption: Users will find value in the extensibility feature and actively contribute to the community. - -## Current state - -[Radius Extenders](https://docs.radapp.io/guides/author-apps/custom/overview/#extenders) enables users to author custom resource types but they are weakly types. They allow you to pass in any property or secret and for cases where the developer/operator need to extend and reference a simple resource type definition. Extenders are for untyped/ weakly typed resources and do not provide a lot of customization for users wanting to have guardrails in their platforms with strongly typed resource definitions following a strict set of rules and restrictions. - -# Scenario: TODO - -## Target customers - - -## Existing customer problem - - -## Desired customer experience outcome - - -### Detailed Customer Experience - - - -## Key investments - - -### Feature 1 - - -### Feature 2 - - -### Feature 3 - - -## Key dependencies and risks - - - - - -## Key assumptions to test and questions to answer - - - -## Current state - \ No newline at end of file From 27bf634993eea041682b1f48d13b21656fc733d3 Mon Sep 17 00:00:00 2001 From: Reshma Abdul Rahim Date: Tue, 18 Jun 2024 15:14:54 -0400 Subject: [PATCH 004/118] Add template docs Signed-off-by: Reshma Abdul Rahim --- README.md | 4 +- ...-06-resource-extensibility-product-spec.md | 2 +- template/YYYY-MM-product-spec-template.md | 92 +++++++++++++++++++ 3 files changed, 95 insertions(+), 3 deletions(-) create mode 100644 template/YYYY-MM-product-spec-template.md diff --git a/README.md b/README.md index d5341393..496d6397 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ This `design-notes` repository contains design proposals, enhancements, and architectural decisions for Radius. It provides a consistent and controlled path to record changes and developments, ensuring clarity and transparency for all stakeholders in the Radius community. -Design notes are used for evaluating the design of **planned** changes and additions to Radius. Do not use this repository for feature requests - please create an issue on the [main Radius repository](https://github.com/radius-project) instead. We create documents in this repo to describe **how** to accomplish something once we have agreement that it is appropriate for the project. +Design notes are used for evaluating the design of **planned** changes and additions to Radius. Do not use this repository for feature requests - please create an issue on the [main Radius repository](https://github.com/radius-project) instead. We create documents in this repo to describe **why** and **how** to accomplish something once we have agreement that it is appropriate for the project. -Minor changes such as documentation updates or small bug fixes may be reviewed and implemented directly via a GitHub issue. For larger changes, such as new feature design, a design note pull-request and review is required. These must get consensus from Radius maintainers and the community, and should follow the [design note template](./template/YYYY-MM-design-template.md) in this repository. +Minor changes such as documentation updates or small bug fixes may be reviewed and implemented directly via a GitHub issue. For larger changes, such as new feature design, a product design note pull-request and review is required. These must get consensus from Radius maintainers and the community. A product specification following the [product spec template] should preceded the [design note template](./template/YYYY-MM-design-template.md) in this repository. For more information on how to contribute to Radius visit [CONTRIBUTING.md](https://github.com/radius-project/radius/blob/main/CONTRIBUTING.md). diff --git a/resources/2024-06-resource-extensibility-product-spec.md b/resources/2024-06-resource-extensibility-product-spec.md index 8a7da3a9..cd92a3e6 100644 --- a/resources/2024-06-resource-extensibility-product-spec.md +++ b/resources/2024-06-resource-extensibility-product-spec.md @@ -93,7 +93,7 @@ Raj is a partner or a system integrator who helps enterprises integrate propriet [Radius Extenders](https://docs.radapp.io/guides/author-apps/custom/overview/#extenders) enables users to author custom resource types but they are weakly types. They allow you to pass in any property or secret and for cases where the developer/operator need to extend and reference a simple resource type definition. Extenders are for untyped/ weakly typed resources and do not provide a lot of customization for users wanting to have guardrails in their platforms with strongly typed resource definitions following a strict set of rules and restrictions. ## Target customers - + diff --git a/template/YYYY-MM-product-spec-template.md b/template/YYYY-MM-product-spec-template.md new file mode 100644 index 00000000..f4449a0b --- /dev/null +++ b/template/YYYY-MM-product-spec-template.md @@ -0,0 +1,92 @@ +# Topic: TODO + +* **Status**: Pending/Approved +* **Author**: Your name (@YourGitHubUserName) + +## Topic Summary + + +### Top level goals + + +### Non-goals (out of scope) + + +## Customer profile and challenges + + +### Customer persona(s) + + +### Challenge(s) faced by the customer + + +### Positive customer outcome + + +## Key scenarios + + +### Scenario 1: TODO + + +### Scenario 2: TODO + + +### Scenario 3: TODO + + +## Key dependencies and risks + + + + + +## Key assumptions to test and questions to answer + + + +## Current state + + +# Scenario: TODO + +## Target customers + + +## Existing customer problem + + +## Desired customer experience outcome + + +### Detailed Customer Experience + + + +## Key investments + + +### Feature 1 + + +### Feature 2 + + +### Feature 3 + + +## Key dependencies and risks + + + + + +## Key assumptions to test and questions to answer + + + +## Current state + \ No newline at end of file From 228bd8ad7b56bd7ebd1868b9428feb00c22b00f9 Mon Sep 17 00:00:00 2001 From: Reshma Abdul Rahim Date: Tue, 18 Jun 2024 15:16:15 -0400 Subject: [PATCH 005/118] Add template docs Signed-off-by: Reshma Abdul Rahim --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 496d6397..e05eaf88 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ This `design-notes` repository contains design proposals, enhancements, and arch Design notes are used for evaluating the design of **planned** changes and additions to Radius. Do not use this repository for feature requests - please create an issue on the [main Radius repository](https://github.com/radius-project) instead. We create documents in this repo to describe **why** and **how** to accomplish something once we have agreement that it is appropriate for the project. -Minor changes such as documentation updates or small bug fixes may be reviewed and implemented directly via a GitHub issue. For larger changes, such as new feature design, a product design note pull-request and review is required. These must get consensus from Radius maintainers and the community. A product specification following the [product spec template] should preceded the [design note template](./template/YYYY-MM-design-template.md) in this repository. +Minor changes such as documentation updates or small bug fixes may be reviewed and implemented directly via a GitHub issue. For larger changes, such as new feature design, a product design note pull-request and review is required. These must get consensus from Radius maintainers and the community. A product specification following the [product spec template](./template/YYYY-MM-product-spec.md) should precede the [design note template](./template/YYYY-MM-design-template.md). For more information on how to contribute to Radius visit [CONTRIBUTING.md](https://github.com/radius-project/radius/blob/main/CONTRIBUTING.md). From 00bf5a05f30a99b7c53ca12a03a180a6981f07a5 Mon Sep 17 00:00:00 2001 From: Reshma Abdul Rahim Date: Tue, 18 Jun 2024 15:17:20 -0400 Subject: [PATCH 006/118] nit Signed-off-by: Reshma Abdul Rahim --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e05eaf88..f53573d6 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ This `design-notes` repository contains design proposals, enhancements, and arch Design notes are used for evaluating the design of **planned** changes and additions to Radius. Do not use this repository for feature requests - please create an issue on the [main Radius repository](https://github.com/radius-project) instead. We create documents in this repo to describe **why** and **how** to accomplish something once we have agreement that it is appropriate for the project. -Minor changes such as documentation updates or small bug fixes may be reviewed and implemented directly via a GitHub issue. For larger changes, such as new feature design, a product design note pull-request and review is required. These must get consensus from Radius maintainers and the community. A product specification following the [product spec template](./template/YYYY-MM-product-spec.md) should precede the [design note template](./template/YYYY-MM-design-template.md). +Minor changes such as documentation updates or small bug fixes may be reviewed and implemented directly via a GitHub issue. For larger changes, such as new feature design, a design note pull-request and review is required. These must get consensus from Radius maintainers and the community. A product specification following the [product spec template](./template/YYYY-MM-product-spec.md) should precede the [design note template](./template/YYYY-MM-design-template.md). For more information on how to contribute to Radius visit [CONTRIBUTING.md](https://github.com/radius-project/radius/blob/main/CONTRIBUTING.md). From a2bfba70c2e0df77cf717593b70e0b3b902a4fa2 Mon Sep 17 00:00:00 2001 From: Reshma Abdul Rahim Date: Tue, 18 Jun 2024 15:38:32 -0400 Subject: [PATCH 007/118] Address feedbac Signed-off-by: Reshma Abdul Rahim --- ...-06-resource-extensibility-product-spec.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/resources/2024-06-resource-extensibility-product-spec.md b/resources/2024-06-resource-extensibility-product-spec.md index cd92a3e6..07063e81 100644 --- a/resources/2024-06-resource-extensibility-product-spec.md +++ b/resources/2024-06-resource-extensibility-product-spec.md @@ -10,8 +10,8 @@ One of the high value extensibility points in Radius is Recipes. We have receive ### Top level goals 1. Enable users to author their applications with custom resource types in Radius without having to write Go code to integrate with Radius components and deploy their application seamlessly. 2. Automatically enable Radius features such as Recipes, Connections, App graph, rad CLI for custom resource types. -3. Enable users to contribute and open-source the custom resource types to the community. -4. Radius uses the resource extensibility for its already built in resource types +3. Enable users to contribute and open-source the custom resource types and recipes to the community. This will accelerate the adoption of Radius across the cloud native community. +4. Radius uses the resource extensibility framework to refactor its already built in resource types. ### Non-goals (out of scope) @@ -21,9 +21,10 @@ One of the high value extensibility points in Radius is Recipes. We have receive **Enterprises**: Platform engineering teams or operations in enterprises focus on streamlining the developer-experience for their organization by defining a set of recommended practices for application teams and provide self-service capabilities for application teams/developers to use. Radius aids the platform engineering efforts with the help of Recipes where the platform engineers or operators define the infrastructure-as-code templates to create resources on demand when application is deployed. One of the major challenges that exists with the Recipes today is the limited number of resources supported. Radius doesn’t provide an extensibility model for users to bring their custom resources, define Recipes and deploy them. **Open-source community**: Building a sustainable open-source community is crucial to the success of any open-source project, including Radius. We need to cultivate an ecosystem for the open-source community to thrive, innovate and produce high quality work. Users from the community are motivated to contribute for different reasons: - - They want to use the project at their work and need a feature, - - The project triggered their interests in the cloud native landscape - - They want to code in a particular language E.g. :Go + - They want to use the project at their work and need a feature, + - The project triggered their interests in the cloud native landscape and want to use the technology. + - They want to code in a particular language E.g. :Go + - They want to integrate their existing tools and technologies with the project Today Radius enables users to get started on contributing to Radius with good-first-issues but doesn’t have a model to promote contributions further. Since the beginning of its open source launch, Dapr created the components repository and invited users to build their own components to unblock their scenarios and in turn folks contributed to the project. Learning from Dapr, Radius needs to have the extensibility points defined for contributors to interact with the project so that they can build out the things that they need to enable their scenarios and in turn the community gets benefitted with those contributions. @@ -93,7 +94,13 @@ Raj is a partner or a system integrator who helps enterprises integrate propriet [Radius Extenders](https://docs.radapp.io/guides/author-apps/custom/overview/#extenders) enables users to author custom resource types but they are weakly types. They allow you to pass in any property or secret and for cases where the developer/operator need to extend and reference a simple resource type definition. Extenders are for untyped/ weakly typed resources and do not provide a lot of customization for users wanting to have guardrails in their platforms with strongly typed resource definitions following a strict set of rules and restrictions. ## Target customers - + +## Define the competition + +| Alternative | Why chosen? | Why not chosen? | What did customer switch? | +|-------------|-------------|-----------------|---------------------------| + ## Existing customer problem From fe12f35dc42a2a099dfbbde21a743aa0a53962a1 Mon Sep 17 00:00:00 2001 From: Reshma Abdul Rahim Date: Wed, 19 Jun 2024 12:57:10 -0400 Subject: [PATCH 008/118] Address feedback Signed-off-by: Reshma Abdul Rahim --- .../2024-06-resource-extensibility-product-spec.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/resources/2024-06-resource-extensibility-product-spec.md b/resources/2024-06-resource-extensibility-product-spec.md index 07063e81..7af27202 100644 --- a/resources/2024-06-resource-extensibility-product-spec.md +++ b/resources/2024-06-resource-extensibility-product-spec.md @@ -1,5 +1,8 @@ # Resource Extensibility (User Defined Resource Types) +* **Status**: Pending +* **Author**: Reshma abdul Rahim (@reshrahim) + ## Summary The cloud native landscape is changing and expanding at a rapid pace like never before. Many enterprises use a wide range of technologies together for achieving their cloud-native strategy. For any technology that’s a newcomer and helps solve a problem in the cloud native landscape, users look for an easy and seamless way to integrate their existing tools and technologies and incrementally adopt the new technology to their strategy. For Radius, we have heard requests from our customers/community to support technologies that their applications are tightly coupled with E.g.: an internal messaging service or a technology they absolutely love E.g.: PostgreSQL/Kafka. @@ -40,7 +43,7 @@ Today Radius enables users to get started on contributing to Radius with good-fi - Developers : Developers are responsible for building the cloud native applications. They are responsible for writing the code, designing and maintaining the applications. -- Open-source contributors : Cloud native open-source contributors are developers who are interested in contributing to the cloud native projects. They are responsible for building the cloud native projects and contributing to the open-source projects. They can be any of the above personas who are interested in contributing to the cloud native projects. +- Open-source contributors : Cloud native open-source contributors can be any of the above personas who are interested in contributing to the cloud native projects. ### Positive customer outcomes - Author and deploy : I can bring my own applications with custom resources/services and integrate with Radius seamlessly. I don’t have to write Go code to integrate with Radius components and can use simple spec to generate the resource definition and integrate with Radius @@ -88,6 +91,7 @@ Raj is a partner or a system integrator who helps enterprises integrate propriet - Assumption: Users will find value in the extensibility feature and actively contribute to the community. +- Assumption: Users will use extensibility in lieu of existing extenders because they want to take advantage of things like strong typing and validation in Radius ## Current state @@ -96,12 +100,6 @@ Raj is a partner or a system integrator who helps enterprises integrate propriet ## Target customers -## Define the competition - -| Alternative | Why chosen? | Why not chosen? | What did customer switch? | -|-------------|-------------|-----------------|---------------------------| - - ## Existing customer problem From 412983c5605bac8536d1898c76c37fa30081654e Mon Sep 17 00:00:00 2001 From: Reshma Abdul Rahim Date: Thu, 20 Jun 2024 16:45:23 -0400 Subject: [PATCH 009/118] Address feedback Signed-off-by: Reshma Abdul Rahim --- README.md | 2 +- ...t-spec.md => 2024-06-resource-extensibility-feature-spec.md} | 0 ...roduct-spec-template.md => YYYY-MM-feature-spec-template.md} | 0 3 files changed, 1 insertion(+), 1 deletion(-) rename resources/{2024-06-resource-extensibility-product-spec.md => 2024-06-resource-extensibility-feature-spec.md} (100%) rename template/{YYYY-MM-product-spec-template.md => YYYY-MM-feature-spec-template.md} (100%) diff --git a/README.md b/README.md index 14008cfe..9b63077b 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ This `design-notes` repository contains design proposals, enhancements, and arch Design notes are used for evaluating the design of **planned** changes and additions to Radius. Do not use this repository for feature requests - please create an issue on the [main Radius repository](https://github.com/radius-project) instead. We create documents in this repo to describe **why** and **how** to accomplish something once we have agreement that it is appropriate for the project. -Minor changes such as documentation updates or small bug fixes may be reviewed and implemented directly via a GitHub issue. For larger changes, such as new feature design, a design note pull-request and review is required. These must get consensus from Radius maintainers and the community. A product specification following the [product spec template](./template/YYYY-MM-product-spec.md) should precede the [design note template](./template/YYYY-MM-design-template.md). +Minor changes such as documentation updates or small bug fixes may be reviewed and implemented directly via a GitHub issue. For larger changes, such as new feature design, a design note pull-request and review is required. These must get consensus from Radius maintainers and the community. A product specification following the [feature spec template](./template/YYYY-MM-feature-spec.md) should precede the [design note template](./template/YYYY-MM-design-template.md). For more information on how to contribute to Radius visit [CONTRIBUTING.md](https://github.com/radius-project/radius/blob/main/CONTRIBUTING.md). diff --git a/resources/2024-06-resource-extensibility-product-spec.md b/resources/2024-06-resource-extensibility-feature-spec.md similarity index 100% rename from resources/2024-06-resource-extensibility-product-spec.md rename to resources/2024-06-resource-extensibility-feature-spec.md diff --git a/template/YYYY-MM-product-spec-template.md b/template/YYYY-MM-feature-spec-template.md similarity index 100% rename from template/YYYY-MM-product-spec-template.md rename to template/YYYY-MM-feature-spec-template.md From cb1921937a35260d4ab90fe9c9fc61d852f045ae Mon Sep 17 00:00:00 2001 From: Reshma Abdul Rahim <61033581+Reshrahim@users.noreply.github.com> Date: Thu, 20 Jun 2024 17:13:53 -0400 Subject: [PATCH 010/118] Update template/YYYY-MM-feature-spec-template.md Co-authored-by: Will <28876888+willtsai@users.noreply.github.com> Signed-off-by: Reshma Abdul Rahim <61033581+Reshrahim@users.noreply.github.com> --- template/YYYY-MM-feature-spec-template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/template/YYYY-MM-feature-spec-template.md b/template/YYYY-MM-feature-spec-template.md index f4449a0b..c38b8df6 100644 --- a/template/YYYY-MM-feature-spec-template.md +++ b/template/YYYY-MM-feature-spec-template.md @@ -54,7 +54,7 @@ ## Target customers -## Existing customer problem +## Details of customer problem ## Desired customer experience outcome From e81550fcc6d2fa9c5dda2a11d9b54bee0dc501aa Mon Sep 17 00:00:00 2001 From: Reshma Abdul Rahim Date: Thu, 20 Jun 2024 17:16:00 -0400 Subject: [PATCH 011/118] Address feedback Signed-off-by: Reshma Abdul Rahim --- ...2024-06-resource-extensibility-feature-spec.md | 15 +-------------- template/YYYY-MM-feature-spec-template.md | 13 ------------- 2 files changed, 1 insertion(+), 27 deletions(-) diff --git a/resources/2024-06-resource-extensibility-feature-spec.md b/resources/2024-06-resource-extensibility-feature-spec.md index 7af27202..46a505a1 100644 --- a/resources/2024-06-resource-extensibility-feature-spec.md +++ b/resources/2024-06-resource-extensibility-feature-spec.md @@ -122,17 +122,4 @@ Step 2 ### Feature 3 - - -## Key dependencies and risks - - - - - -## Key assumptions to test and questions to answer - - - -## Current state - \ No newline at end of file + \ No newline at end of file diff --git a/template/YYYY-MM-feature-spec-template.md b/template/YYYY-MM-feature-spec-template.md index c38b8df6..670e5c84 100644 --- a/template/YYYY-MM-feature-spec-template.md +++ b/template/YYYY-MM-feature-spec-template.md @@ -77,16 +77,3 @@ Step 2 ### Feature 3 - -## Key dependencies and risks - - - - - -## Key assumptions to test and questions to answer - - - -## Current state - \ No newline at end of file From a892ba42b55f93c5d6c332059bbda2b10e45f2fe Mon Sep 17 00:00:00 2001 From: Reshma Abdul Rahim Date: Thu, 20 Jun 2024 17:23:16 -0400 Subject: [PATCH 012/118] Address feedback Signed-off-by: Reshma Abdul Rahim --- resources/2024-06-resource-extensibility-feature-spec.md | 5 +---- template/YYYY-MM-feature-spec-template.md | 5 ----- 2 files changed, 1 insertion(+), 9 deletions(-) diff --git a/resources/2024-06-resource-extensibility-feature-spec.md b/resources/2024-06-resource-extensibility-feature-spec.md index 46a505a1..59c58f89 100644 --- a/resources/2024-06-resource-extensibility-feature-spec.md +++ b/resources/2024-06-resource-extensibility-feature-spec.md @@ -97,10 +97,7 @@ Raj is a partner or a system integrator who helps enterprises integrate propriet [Radius Extenders](https://docs.radapp.io/guides/author-apps/custom/overview/#extenders) enables users to author custom resource types but they are weakly types. They allow you to pass in any property or secret and for cases where the developer/operator need to extend and reference a simple resource type definition. Extenders are for untyped/ weakly typed resources and do not provide a lot of customization for users wanting to have guardrails in their platforms with strongly typed resource definitions following a strict set of rules and restrictions. -## Target customers - - -## Existing customer problem +## Details of the customer problem ## Desired customer experience outcome diff --git a/template/YYYY-MM-feature-spec-template.md b/template/YYYY-MM-feature-spec-template.md index 670e5c84..927ed32c 100644 --- a/template/YYYY-MM-feature-spec-template.md +++ b/template/YYYY-MM-feature-spec-template.md @@ -49,11 +49,6 @@ ## Current state -# Scenario: TODO - -## Target customers - - ## Details of customer problem From 67c0ecbd9f16af534ea90ab29b4280146de7c8ca Mon Sep 17 00:00:00 2001 From: Reshma Abdul Rahim Date: Tue, 16 Jul 2024 11:56:04 -0400 Subject: [PATCH 013/118] WIP --- resources/2024-06-resource-extensibility-feature-spec.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/resources/2024-06-resource-extensibility-feature-spec.md b/resources/2024-06-resource-extensibility-feature-spec.md index 59c58f89..7cff5bb8 100644 --- a/resources/2024-06-resource-extensibility-feature-spec.md +++ b/resources/2024-06-resource-extensibility-feature-spec.md @@ -97,9 +97,6 @@ Raj is a partner or a system integrator who helps enterprises integrate propriet [Radius Extenders](https://docs.radapp.io/guides/author-apps/custom/overview/#extenders) enables users to author custom resource types but they are weakly types. They allow you to pass in any property or secret and for cases where the developer/operator need to extend and reference a simple resource type definition. Extenders are for untyped/ weakly typed resources and do not provide a lot of customization for users wanting to have guardrails in their platforms with strongly typed resource definitions following a strict set of rules and restrictions. -## Details of the customer problem - - ## Desired customer experience outcome @@ -119,4 +116,4 @@ Step 2 ### Feature 3 - \ No newline at end of file + From 308df0c9c4644f0ef67b75ebf0947be04430b6ec Mon Sep 17 00:00:00 2001 From: Reshma Abdul Rahim Date: Tue, 30 Jul 2024 11:58:31 -0400 Subject: [PATCH 014/118] Add resource extensibility Signed-off-by: Reshma Abdul Rahim --- ...-06-resource-extensibility-feature-spec.md | 119 ----- ...-06-resource-extensibility-feature-spec.md | 431 ++++++++++++++++++ .../resource-extensbility/images/errors.png | Bin 0 -> 102022 bytes .../images/intellisense.png | Bin 0 -> 109965 bytes 4 files changed, 431 insertions(+), 119 deletions(-) delete mode 100644 resources/2024-06-resource-extensibility-feature-spec.md create mode 100644 resources/resource-extensbility/2024-06-resource-extensibility-feature-spec.md create mode 100644 resources/resource-extensbility/images/errors.png create mode 100644 resources/resource-extensbility/images/intellisense.png diff --git a/resources/2024-06-resource-extensibility-feature-spec.md b/resources/2024-06-resource-extensibility-feature-spec.md deleted file mode 100644 index 7cff5bb8..00000000 --- a/resources/2024-06-resource-extensibility-feature-spec.md +++ /dev/null @@ -1,119 +0,0 @@ -# Resource Extensibility (User Defined Resource Types) - -* **Status**: Pending -* **Author**: Reshma abdul Rahim (@reshrahim) - -## Summary -The cloud native landscape is changing and expanding at a rapid pace like never before. Many enterprises use a wide range of technologies together for achieving their cloud-native strategy. For any technology that’s a newcomer and helps solve a problem in the cloud native landscape, users look for an easy and seamless way to integrate their existing tools and technologies and incrementally adopt the new technology to their strategy. For Radius, we have heard requests from our customers/community to support technologies that their applications are tightly coupled with E.g.: an internal messaging service or a technology they absolutely love E.g.: PostgreSQL/Kafka. - -We need to enable the open-source community to build and experiment with imperfect things. We need to provide an extensibility model that supports “Bring your own technology”, define and use it with Radius. This will help us to meet the community where they are and enable them to experiment and leverage their work as open-source contributions. - -One of the high value extensibility points in Radius is Recipes. We have received interests to create custom resource types, define Recipes for the custom resource types and use it in the Radius application. Today Radius Extenders helps in creating custom resource types, but they are untyped and have limitations. The goal of providing resource extensibility is to empower developers or infrastructure operators to author and run their applications with custom resource types seamlessly in Radius and use all the other features such as Recipes, connections and app graph with ease and flexibility. - -### Top level goals -1. Enable users to author their applications with custom resource types in Radius without having to write Go code to integrate with Radius components and deploy their application seamlessly. -2. Automatically enable Radius features such as Recipes, Connections, App graph, rad CLI for custom resource types. -3. Enable users to contribute and open-source the custom resource types and recipes to the community. This will accelerate the adoption of Radius across the cloud native community. -4. Radius uses the resource extensibility framework to refactor its already built in resource types. - -### Non-goals (out of scope) - - - -## Customer profile and challenges -**Enterprises**: Platform engineering teams or operations in enterprises focus on streamlining the developer-experience for their organization by defining a set of recommended practices for application teams and provide self-service capabilities for application teams/developers to use. Radius aids the platform engineering efforts with the help of Recipes where the platform engineers or operators define the infrastructure-as-code templates to create resources on demand when application is deployed. One of the major challenges that exists with the Recipes today is the limited number of resources supported. Radius doesn’t provide an extensibility model for users to bring their custom resources, define Recipes and deploy them. - -**Open-source community**: Building a sustainable open-source community is crucial to the success of any open-source project, including Radius. We need to cultivate an ecosystem for the open-source community to thrive, innovate and produce high quality work. Users from the community are motivated to contribute for different reasons: - - They want to use the project at their work and need a feature, - - The project triggered their interests in the cloud native landscape and want to use the technology. - - They want to code in a particular language E.g. :Go - - They want to integrate their existing tools and technologies with the project - -Today Radius enables users to get started on contributing to Radius with good-first-issues but doesn’t have a model to promote contributions further. Since the beginning of its open source launch, Dapr created the components repository and invited users to build their own components to unblock their scenarios and in turn folks contributed to the project. Learning from Dapr, Radius needs to have the extensibility points defined for contributors to interact with the project so that they can build out the things that they need to enable their scenarios and in turn the community gets benefitted with those contributions. - -### Customer persona(s) - -- Platform engineers: Platform engineers are responsible for streamlining the developer-experience for their organization by defining a set of recommended practices for application teams and provide self-service capabilities for application teams/developers to use. They are responsible for building the platform and providing the necessary tools and services for the application teams to deploy their applications. - -- IT Operators: IT operators are responsible for managing the infrastructure and ensuring that the applications are running smoothly. They are responsible for maintaining the infrastructure and providing support for the infrastructure. They are the primary users of Radius Recipes as they are responsible for defining the infrastructure-as-code templates for the applications. - -- System Reliability Engineers (SREs) : SREs are responsible for ensuring the reliability of the applications and services that are deployed in the cloud. They are responsible for maintaining the infrastructure and ensuring that the applications are running smoothly. They maintain the infrastructure-as-code templates and provide support for the applications that are deployed. - -- System integrators : System integrators are partners who help enterprises integrate proprietary services with cloud native applications. They are responsible for designing and building cloud native applications on behalf of their customers. - -- Developers : Developers are responsible for building the cloud native applications. They are responsible for writing the code, designing and maintaining the applications. - -- Open-source contributors : Cloud native open-source contributors can be any of the above personas who are interested in contributing to the cloud native projects. - -### Positive customer outcomes -- Author and deploy : I can bring my own applications with custom resources/services and integrate with Radius seamlessly. I don’t have to write Go code to integrate with Radius components and can use simple spec to generate the resource definition and integrate with Radius - -- Recipes for user defined types: I can create Recipes for the custom resource types and deploy via Radius - -- OSS contributions: I can create and contribute Recipes for the custom resource types for the community to use. - -## Key scenarios - -### Scenario 1: Deb integrates the Budgets app with Radius -Deb, a platform engineer at a Financial Services company, wants to integrate the Budgets app with Radius. The Budgets app relies on an internal messaging service called Plaid. Deb wants to use Plaid as a resource type in Radius to deploy the application seamlessly. He needs a way to define and use Plaid as a custom resource type in Radius without having to write Go code. This will enable him to leverage all the features of Radius, such as Recipes, Connections, and the rad CLI, with ease and flexibility. - -### Scenario 2: Amy contributes and open-sources PostgreSQL support to Radius -Amy is a system integrator who helps customers build cloud native applications on AWS. Amy heard about Radius and starts integrating their customer workloads in Radius. She sees a lot of her scenarios involve PostgreSQL and finds Radius doesn’t support that yet. She wants to contribute the PostgreSQL support to Radius and open source it so anyone can use it - -### Scenario 3: Raj publishes Recipes for proprietary services -Raj is a partner or a system integrator who helps enterprises integrate proprietary service for eg : Oracle database in their cloud native applications. Raj tries out Radius and wants to write Recipes to create an Oracle Database with a standard set of best practices and policies integrated. He works with a lot of customers who are wanting to use the Oracle Database recipe in their applications. - -## Key dependencies and risks - - - - - - -- Dependency: Bicep compiler merge support - - We need to ensure that the ongoing Bicep compiler merge work is complete so that custom resource types can be dynamically generated for the user defined resource types. - - Mitigation: Work closely with the Bicep team to ensure that the merge is completed on time and that the necessary features are available to enable custom resource types in Radius . - -- Risk: Adoption and community engagement - - There is a risk that users may not fully embrace the extensibility feature or contribute custom resource types to the community. - - Mitigation: Actively engage with users, provide clear documentation and resources, and foster a supportive and inclusive community to encourage adoption and contributions. - -- Risk: Compatibility and maintainability - - As more custom resource types are added to Radius, there is a risk of compatibility issues and increased maintenance overhead. - - Mitigation: Implement thorough testing and versioning strategies to ensure compatibility, and establish clear guidelines for maintaining custom resource types. - -- Risk: Security and trust - - Allowing users to contribute custom resource types introduces potential security risks and the need to establish trust in the community-contributed code. - - Mitigation: Implement strict security measures, such as code reviews and vulnerability scanning, and establish a transparent review process for community contributions. - -## Key assumptions to test and questions to answer - - - -- Assumption: Users will find value in the extensibility feature and actively contribute to the community. -- Assumption: Users will use extensibility in lieu of existing extenders because they want to take advantage of things like strong typing and validation in Radius - -## Current state - -[Radius Extenders](https://docs.radapp.io/guides/author-apps/custom/overview/#extenders) enables users to author custom resource types but they are weakly types. They allow you to pass in any property or secret and for cases where the developer/operator need to extend and reference a simple resource type definition. Extenders are for untyped/ weakly typed resources and do not provide a lot of customization for users wanting to have guardrails in their platforms with strongly typed resource definitions following a strict set of rules and restrictions. - -## Desired customer experience outcome - - -### Detailed Customer Experience - - - -## Key investments - - -### Feature 1 - - -### Feature 2 - - -### Feature 3 - diff --git a/resources/resource-extensbility/2024-06-resource-extensibility-feature-spec.md b/resources/resource-extensbility/2024-06-resource-extensibility-feature-spec.md new file mode 100644 index 00000000..7f917c63 --- /dev/null +++ b/resources/resource-extensbility/2024-06-resource-extensibility-feature-spec.md @@ -0,0 +1,431 @@ +# Resource Extensibility (User Defined Resource Types) + +* **Status**: Pending +* **Author**: Reshma abdul Rahim (@reshrahim) + +## Summary +The cloud native landscape is changing and expanding at a rapid pace like never before. Many enterprises use a wide range of technologies together for achieving their cloud-native strategy. For any technology that’s a newcomer and helps solve a problem in the cloud native landscape, users look for an easy and seamless way to integrate their existing tools and technologies and incrementally adopt the new technology to their strategy. For Radius, we have heard requests from our customers/community to support technologies that their applications are tightly coupled with E.g.: an internal messaging service or a technology they absolutely love E.g.: PostgreSQL/Kafka. + +We need to enable the open-source community to build and experiment with imperfect things. We need to provide an extensibility model that supports “Bring your own technology”, define and use it with Radius. This will help us to meet the community where they are and enable them to experiment and leverage their work as open-source contributions. + +One of the high value extensibility points in Radius is Recipes. We have received interests to create custom resource types, define Recipes for the custom resource types and use it in the Radius application. Today Radius Extenders helps in creating custom resource types, but they are untyped and have limitations. The goal of providing resource extensibility is to empower developers or infrastructure operators to author and run their applications with custom resource types seamlessly in Radius and use all the other features such as Recipes, connections and app graph with ease and flexibility. + +### Top level goals +1. Enable users to author their applications with custom resource types in Radius without having to write Go code to integrate with Radius components and deploy their application seamlessly. +2. Automatically enable Radius features such as Recipes, Connections, App graph, rad CLI for custom resource types. +3. Enable users to contribute and open-source the custom resource types and recipes to the community. This will accelerate the adoption of Radius across the cloud native community. +4. Radius uses the resource extensibility framework to refactor its already built in resource types. + +### Non-goals (out of scope) + + + +## Customer profile and challenges +**Enterprises**: Platform engineering teams or operations in enterprises focus on streamlining the developer-experience for their organization by defining a set of recommended practices for application teams and provide self-service capabilities for application teams/developers to use. Radius aids the platform engineering efforts with the help of Recipes where the platform engineers or operators define the infrastructure-as-code templates to create resources on demand when application is deployed. One of the major challenges that exists with the Recipes today is the limited number of resources supported. Radius doesn’t provide an extensibility model for users to bring their custom resources, define Recipes and deploy them. + +**Open-source community**: Building a sustainable open-source community is crucial to the success of any open-source project, including Radius. We need to cultivate an ecosystem for the open-source community to thrive, innovate and produce high quality work. Users from the community are motivated to contribute for different reasons: + - They want to use the project at their work and need a feature, + - The project triggered their interests in the cloud native landscape and want to use the technology. + - They want to code in a particular language E.g. :Go + - They want to integrate their existing tools and technologies with the project + +Today Radius enables users to get started on contributing to Radius with good-first-issues but doesn’t have a model to promote contributions further. Since the beginning of its open source launch, Dapr created the components repository and invited users to build their own components to unblock their scenarios and in turn folks contributed to the project. Learning from Dapr, Radius needs to have the extensibility points defined for contributors to interact with the project so that they can build out the things that they need to enable their scenarios and in turn the community gets benefitted with those contributions. + +### Customer persona(s) + +- Platform engineers: Platform engineers are responsible for streamlining the developer-experience for their organization by defining a set of recommended practices for application teams and provide self-service capabilities for application teams/developers to use. They are responsible for building the platform and providing the necessary tools and services for the application teams to deploy their applications. + +- IT Operators: IT operators are responsible for managing the infrastructure and ensuring that the applications are running smoothly. They are responsible for maintaining the infrastructure and providing support for the infrastructure. They are the primary users of Radius Recipes as they are responsible for defining the infrastructure-as-code templates for the applications. + +- System Reliability Engineers (SREs) : SREs are responsible for ensuring the reliability of the applications and services that are deployed in the cloud. They are responsible for maintaining the infrastructure and ensuring that the applications are running smoothly. They maintain the infrastructure-as-code templates and provide support for the applications that are deployed. + +- System integrators : System integrators are partners who help enterprises integrate proprietary services with cloud native applications. They are responsible for designing and building cloud native applications on behalf of their customers. + +- Developers : Developers are responsible for building the cloud native applications. They are responsible for writing the code, designing and maintaining the applications. + +- Open-source contributors : Cloud native open-source contributors can be any of the above personas who are interested in contributing to the cloud native projects. + +### Positive customer outcomes +- Author and deploy : I can bring my own applications with custom resources/services and integrate with Radius seamlessly. I don’t have to write Go code to integrate with Radius components and can use simple spec to generate the resource definition and integrate with Radius + +- Recipes for user defined types: I can create Recipes for the custom resource types and deploy via Radius + +- OSS contributions: I can create and contribute Recipes for the custom resource types for the community to use. + +## Key scenarios + +### Scenario 1: Deb integrates the Budgets app with Radius +Deb, a platform engineer at a Financial Services company, wants to integrate the Budgets app with Radius. The Budgets app relies on an internal messaging service called Plaid. Deb wants to use Plaid as a resource type in Radius to deploy the application seamlessly. He needs a way to define and use Plaid as a custom resource type in Radius without having to write Go code. This will enable him to leverage all the features of Radius, such as Recipes, Connections, and the rad CLI, with ease and flexibility. + +### Scenario 2: Amy contributes and open-sources PostgreSQL support to Radius +Amy is a system integrator who helps customers build cloud native applications on AWS. Amy heard about Radius and starts integrating their customer workloads in Radius. She sees a lot of her scenarios involve PostgreSQL and finds Radius doesn’t support that yet. She wants to contribute the PostgreSQL support to Radius and open source it so anyone can use it + +### Scenario 3: Raj publishes Recipes for proprietary services +Raj is a partner or a system integrator who helps enterprises integrate proprietary service for eg : Oracle database in their cloud native applications. Raj tries out Radius and wants to write Recipes to create an Oracle Database with a standard set of best practices and policies integrated. He works with a lot of customers who are wanting to use the Oracle Database recipe in their applications. + +## Key dependencies and risks + + + + + + +- Dependency: Bicep compiler merge support + - We need to ensure that the ongoing Bicep compiler merge work is complete so that custom resource types can be dynamically generated for the user defined resource types. + - Mitigation: Work closely with the Bicep team to ensure that the merge is completed on time and that the necessary features are available to enable custom resource types in Radius . + +- Risk: Adoption and community engagement + - There is a risk that users may not fully embrace the extensibility feature or contribute custom resource types to the community. + - Mitigation: Actively engage with users, provide clear documentation and resources, and foster a supportive and inclusive community to encourage adoption and contributions. + +- Risk: Compatibility and maintainability + - As more custom resource types are added to Radius, there is a risk of compatibility issues and increased maintenance overhead. + - Mitigation: Implement thorough testing and versioning strategies to ensure compatibility, and establish clear guidelines for maintaining custom resource types. + +- Risk: Security and trust + - Allowing users to contribute custom resource types introduces potential security risks and the need to establish trust in the community-contributed code. + - Mitigation: Implement strict security measures, such as code reviews and vulnerability scanning, and establish a transparent review process for community contributions. + +## Key assumptions to test and questions to answer + + + +- Assumption: Users will find value in the extensibility feature and actively contribute to the community. +- Assumption: Users will use extensibility in lieu of existing extenders because they want to take advantage of things like strong typing and validation in Radius + +## Current state + + +### Existing solutions + +| Solution | Description | Challenges | +|----------|-------------|------------| +| Kubernetes CRD's | Kubernetes Custom Resource Definitions (CRDs) are a way to extend the Kubernetes API and create custom resource types. CRDs allow users to define their own resource types and controllers to manage those resources. CRDs are widely used in the Kubernetes ecosystem to create custom resources for various use cases. | Complicated to author CRDs ; Versioning and Maintenance ; Ensuring backward compatibility | +| Crossplane XRD's | Built on top of Kubernetes CRD's | | + +### Current state in Radius + +[Radius Extenders](https://docs.radapp.io/guides/author-apps/custom/overview/#extenders) enables users to author custom resource types but they are weakly types. They allow you to pass in any property or secret and for cases where the developer/operator need to extend and reference a simple resource type definition. Extenders are for untyped/ weakly typed resources and do not provide a lot of customization for users wanting to have guardrails in their platforms with strongly typed resource definitions following a strict set of rules and restrictions. + +## Existing customer problem + + +### Customer Jobs to be done + +As a platform engineer trying to build a custom platform for application development, I have the following jobs to be done and requirements to meet: + +#### Main job : Build a custom platform for application development + +| Related jobs | Functional aspects | Emotional aspects | +| ------------- | ------------------ | ----------------- | +| Define the set of key technologies for the enterprise applications | Set of technologies that organizations intend to use for their applications based on the nature of technology, open-source support, documentation support, existing vendor relations, expertise in the team | Easy to use, troubleshoot, sense of service ownership | +| Specify the contract for the key services in the application platform | Author a schema for the custom resources easily with auto guidance tools | Simple tools that enables the schema authoring, uniformity and consistency | +| Iterating and testing the application platform | Providing a productive inner loop for development and testing | Simple and easy way to iterate on changes, test and deploy them | +| Ship the custom platform | Registering the API's to the platform, providing documentation, onboarding and support | intuitive, seamless, collaborative | +| Maintain the custom platform | Versioning and maintaining the API's | Ease of support, sense of ownership (decision making) | +| Support for compliance and security | Compatibility and security policies | Trust the platform | +| Open-source custom resources | Repository and pipeline to validate, testing the infrastructure and publishing | Desire to contribute, easy to use, low overhead /dependency to publish | + +As an IT operator and developer trying to build and maintain the application, I have the following jobs to be done and requirements to meet: + +#### Main job : Use the custom platform to build and maintain the application + +| Related jobs | Functional aspects | Emotional aspects | +| ------------- | ------------------ | ----------------- | +| Use the custom app platform to build my application | Learn, define and consume the APIs | Easy to use, adopt, low concept count | +| Manage and deploy the custom resources in the application platform| Create a IaC template for the custom resource type with compliance and other policies | Easy to author, test and deploy | +| Maintain the application over time | Versioning of the custom resources and enabling automatic upgrades | Less overhead to maintain | +| Troubleshoot the custom application platform | Tools or experiences in Dashboard that enables users to troubleshoot and manage the custom resources | Immediate access to key data for troubleshooting, simple and intuitive | +| Open sourcing templates | Repository and pipeline to validate, testing the infrastructure and publishing | Desire to contribute, easy to use, low overhead /dependency to publish | + +## Solution approach in Radius + +### Main job : Build a custom platform for application development + +#### Define the set of key technologies for the enterprise applications +Enterprises choose technologies based on the nature of technology, open-source support, documentation support, existing vendor relations, expertise in the team. Radius can provide the following to the customers: + +*Community supported assets* : Community supported assets include the resource type definitions and IaC templates to deploy and manage resources in applications. Radius can enable the community to provide and use the assets for the prevalent cloud native technologies. This will help customers to use pre-existing assets IaC templates and definitions in their applications without having to author them from scratch. + +*Community supported assets meets their requirements* : Enterprises have a wide range of requirements for their applications based on the nature of the application, market, region, hosting models,compliance and security policies. Radius can enable the community to provide and use the resource type definitions and IaC templates that meet the requirements of the enterprises and meet them where they are. This will enable customers to build what they want via Radius thus unblocking them to build their applications. + +*Maintenance and support for the community supported assets* : Radius can provide the necessary tools and services to maintain and support the community supported assets. This will help the community to contribute, maintain the assets and provide support to the users who are using the assets. + +**Solution in Radius** + +1. Resource extensibility for defining the custom resource types in Radius +1. Recipes for the custom resource types +1. Community supported resource type definitions +1. Community supported Recipes +1. Radius auto generates AWS, Azure Recipes from the definitions (Recipes for any resource) + +We will cover the design and user experience for all the above solutions except for "Recipes for any resource" in this document to keep the scope of the work simple. + +#### Specify the contract for the key services in the application platform + +As a platform engineer, I want to provide the custom platform with the following: + +*Resource schema authoring*: Define a schema for the custom resource types that my application uses in Radius. The schema defines the structure and properties of the custom resource type. + +*Auto guidance for schema authoring*: The resource schema authoring tool provides auto guidance and validation to help the user author the schema. The auto guidance tool provides suggestions and recommendations to the user based on the schema that they are authoring. + +*Consistency and uniformity in the schema*: The authored resource schema is consistent and uniform across all the custom resource types that the user defines. + +**Solution in Radius** + +*Schema authoring format* + +| Schema Format | Why chose? | Why not to chose? | +|---------------|------------|-------------------| +| Typespec | Developer friendly; Maintenance and upgrades are easier; Errors and guidance violations at development time | Microsoft developed language; May not be widely adopted by the cloud-native communities ; Yet another language to adopt | +| OpenAPI YAML/JSON | More common and standard format across the open-source communities ; K8s CRD's follow the structure of Open API | Managing versions and ensuring backward compatibility is challenging | + +*User groups and their needs* + +There are two types of users that we need to cater to: +1. Users who are new or comfortable with experimenting a new schema format typespec +1. Users who are familiar with openAPI schema format and are proficient in defining the schema in YAML/JSON format + +Hence, we need to support both the schema formats in Radius to support both user groups. + +*User experience* + +1. Deb is a platform engineer at Contoso open to use typespec and wants to author a custom resource Plaid in Radius + + Pre-requisites: User has typespec compiler/CLI installed + + 1. Deb uses the radCLI to scaffold a template typespec definition + + ```bash + rad resource-provider init contoso --template-kind typespec + ``` + A sample plaid.tsp file and manifest files are created in the application folder with all the typespec dependencies installed. + + Question :Can we build on top of `tsp init` which is used to set up a typespec project with a sample template? The other option is to use `rad resource-provider new` to scaffold a template typespec definition and the user takes care of the typespec dependencies and setup which might be a confusing. + + 1. Deb authors the schema for plaid in typespec format + + ``` + import "@typespec/http"; + import "@typespec/rest"; + import "@typespec/openapi3"; + import "@typespec/versioning"; + + using TypeSpec.Http; + using TypeSpec.Rest; + using TypeSpec.Versioning; + + @service({title: "Contoso"}) + @server("http://contoso.plaid.com", "endpoint for plaid service") + @versioned(Versions) + namespace Contoso; + + @route("/planes/radius/Contoso.Messaging") + namespace plaid { + model plaid { + name:string; + description:string; + queue:string; + } + } + + ``` + + 1. VSCode Type spec extension warns Deb on the errors and warnings as he types + + ![alt text](images/errors.png) + + 1. Deb uses intellisense to autocomplete the schema and properties + + ![alt text](images/intellisense.png) + + 1. Deb chooses a version for the schema + + ``` + import "@typespec/http"; + import "@typespec/rest"; + import "@typespec/openapi3"; + import "@typespec/versioning"; + + using TypeSpec.Http; + using TypeSpec.Rest; + using TypeSpec.Versioning; + + @service({title: "Contoso"}) + @server("http://contoso.plaid.com", "endpoint for plaid service") + @versioned(Versions) + namespace Contoso; + + @route("/planes/radius/Contoso.Messaging") + namespace plaid { + model plaid { + name:string; + description:string; + queue:string; + } + } + + enum Versions { + v1, + } + ``` + 1. Deb registers the schema in Radius + + ```bash + rad resource-provider register contoso --template-kind typespec -e myenv -v v1 + ``` + Radius complies the schema and registers the custom resource type Plaid in UCP + + 1. Deb lists the resources types he has in his environment + + ```bash + rad resource-provider list -e myenv + ``` + Radius lists the custom resource types that Deb has registered in his environment + +2. Amy is a system integrator who is familiar with OpenAPI schema format and wants to author a custom resource PostgreSQL in Radius + + 1. Amy uses the radCLI to scaffold a yaml template definition + + ```bash + rad resource-provider init plaid --template-kind yaml + ``` + A sample yaml file is created in the application folder. + + 1. Amy authors the schema for plaid in typespec format + + ``` + namespace: 'Applications.Datastores' + apiVersion: 'v1' + scope: '/planes/radius/Applications.Datastores' + resourceTypes: + 'Applications.Datastores/postgreSQL': + name: 'Name of the resource' + description: 'PostgreSQL' + properties: + required: ['host', 'env', 'secrets'] + host: + type: 'string' + description: 'Hostname' + env: + type: 'string' + description: 'Radius environment' + app: + type: 'string' + description: 'Radius application' + secrets: + connectionstring: + type: 'string' + description: 'Connection string for PostgreSQL' + ``` + + 1. Amy adds a version for the schema + + ``` + namespace: 'Applications.Datastores' + apiVersion: 'v1' + scope: '/planes/radius/Applications.Datastores' + resourceTypes: + 'Applications.Datastores/postgreSQL': + name: 'Name of the resource' + description: 'PostgreSQL' + properties: + required: ['host', 'env', 'secrets'] + host: + type: 'string' + description: 'Hostname' + env: + type: 'string' + description: 'Radius environment' + app: + type: 'string' + description: 'Radius application' + secrets: + connectionstring: + type: 'string' + description: 'Connection string for PostgreSQL' + ``` + 1. Amy registers the postgreSQL schema to an existing provider in Radius + + ```bash + rad resource-type add -rp Applications --template-kind yaml -e myenv -v v1 + ``` + + Radius complies the schema and registers the custom resource type Plaid in UCP + + Question : Will Applications continue to be a resource provider to accept new resource types ? + +#### Iterating and testing the application platform + + As a platform engineer, I want to provide a productive inner loop for development and testing the application platform. Simple and easy way to iterate on changes, test and deploy them + +**Solution in Radius** +1. Bicep tooling support to test and deploy the custom resource types - rad CLI support to generate and publish the Bicep types for the custom resources to the registry. +1. Documentation to guide the users on how to test and deploy the custom resource types in Radius + +*User groups and their needs* + +There are two types of users that we need to cater to: +1. Users who have registered schema using typespec schema format +1. Users who have registered schema using yaml schema format + +*User experience* + +1. Deb compiles the typespec schema + + ```bash + tsp compile + ``` + The typespec schema is compiled and validated for any errors and warnings + +1. Deb publishes the bicep types to a registry + + ```bash + rad publish-bicep-types --file contoso.tsp --registry myregistry + ``` + The `contoso.tsp` is complied into open api specs; the index.json and types.json files are generated and published to the registry for the custom resource type Plaid and the new resource provider is added to `bicepconfig.json` + + { + "experimentalFeaturesEnabled": { + "extensibility": true, + "extensionRegistry": true, + "dynamicTypeLoading": true + }, + "extensions": { + "radius": "br:biceptypes.azurecr.io/radius:latest", + "aws": "br:biceptypes.azurecr.io/aws:latest" + "Contoso": "br:biceptypes.azurecr.io/contoso:latest" + } + } + +1. Create a app.bicep with plaid resource type + + ```bicep + param plaidName string + param plaidDescription string + param plaidQueue string + + resource plaid 'Contoso.Messaging/Plaid@v1' = { + name: plaidName + description: plaidDescription + queue: plaidQueue + } + ``` +1. Deb uses the rad CLI to deploy the application with the custom resource type Plaid + + ```bash + rad deploy app.bicep + ``` + The application is deployed with the custom resource type Plaid in Radius. Deb can iterate on the changes, compile and test the application with the custom resource type. + +#### Ship the custom platform + +As a platform engineer, I want to register the API's to the platform, provide documentation, onboarding and support. Intuitive, seamless, collaborative + +**Solution in Radius** + +1. End-end-documentation for the custom resource types - Radius provides documentation to the users on how to author, test and deploy the custom resource types in Radius. + 1. Typespec samples and documentation - Provide samples and documentation for the users to author the schema in typespec format + 1. Documentation for generating Radius-Bicep types - Reuse existing pipelines and GH workflows used in Radius to generate Radius types in Bicep as an example and provide documentation to the users on how to build and publish the custom resource types in Radius. + + diff --git a/resources/resource-extensbility/images/errors.png b/resources/resource-extensbility/images/errors.png new file mode 100644 index 0000000000000000000000000000000000000000..56b4dceadfb80999a074f5c96f93eda5a7cc1ecc GIT binary patch literal 102022 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