docs: Add API reference #592

michaelawyu · 2023-11-06T06:24:00Z

Description of your changes

This PR adds API reference documentation.

How has this code been tested

N/A

Special notes for your reviewer

N/A

ryanzhang-oss · 2023-11-06T06:31:00Z

docs/api-references.md

+
+
+### Resource Types
+- [InternalMemberCluster](#internalmembercluster)


please only include external facing API

I will hide InternalMemberCluster and AppliedWorks.

Also removed reference to v1alpha1 APIs.

britaniar · 2023-11-07T21:14:08Z

docs/api-references.md

+
+
+| Field | Description |
+| --- | --- |


Confusion on why there are two kinds and two apiVersions

britaniar · 2023-11-07T21:16:01Z

docs/api-references.md

+- [MemberClusterList](#memberclusterlist)
+
+| Field | Description |
+| --- | --- |


Same as MemberClusterList, why is there two?

britaniar · 2023-11-07T23:15:26Z

docs/api-references.md

+
+
+
+ClusterResourceBinding represents a scheduling decision that binds a group of resources to a cluster. It MUST have a label named `CRPTrackingLabel` that points to the cluster resource policy that creates it.


Since this is the first instance of CRPTrackingLabel I recommend putting what it is here as well, or instead.

britaniar · 2023-11-07T23:17:56Z

docs/api-references.md

+
+
+ClusterResourcePlacement is used to select cluster scoped resources, including built-in resources and custom resources, and placement them onto selected member clusters in a fleet. 
+ If a namespace is selected, ALL the resources under the namespace are placed to the target clusters. Note that you can't select the following resources: - reserved namespaces including: default, kube-* (reserved for Kubernetes system namespaces), fleet-* (reserved for fleet system namespaces). - reserved fleet resource types including: MemberCluster, InternalMemberCluster, ClusterResourcePlacement, ClusterSchedulingPolicySnapshot, ClusterResourceSnapshot, ClusterResourceBinding, etc. 


Bold the note for reserved namespaces to be sure the user catches it.

britaniar · 2023-11-07T23:19:08Z

docs/api-references.md

+
+
+ClusterResourcePlacement is used to select cluster scoped resources, including built-in resources and custom resources, and placement them onto selected member clusters in a fleet. 
+ If a namespace is selected, ALL the resources under the namespace are placed to the target clusters. Note that you can't select the following resources: - reserved namespaces including: default, kube-* (reserved for Kubernetes system namespaces), fleet-* (reserved for fleet system namespaces). - reserved fleet resource types including: MemberCluster, InternalMemberCluster, ClusterResourcePlacement, ClusterSchedulingPolicySnapshot, ClusterResourceSnapshot, ClusterResourceBinding, etc. 


@ryanzhang-oss are we wanting to include InternalMemberCluster here?

no, that's an internal object.

britaniar · 2023-11-07T23:23:06Z

docs/api-references.md

+
+| Field | Description |
+| --- | --- |
+| `resourceSelectors` _[ClusterResourceSelector](#clusterresourceselector) array_ | ResourceSelectors is an array of selectors used to select cluster scoped resources. The selectors are `ORed`. You can have 1-100 selectors. |


Define ORed, this might be the first time a user sees this.

britaniar · 2023-11-07T23:47:39Z

docs/api-references.md

+
+
+
+Manifest represents a resource to be deployed on spoke cluster.


First mention of spoke cluster might need a small definition

britaniar · 2023-11-07T23:49:21Z

docs/api-references.md

+
+
+
+PlacementPolicy contains the rules to select target member clusters to place the selected resources. Note that only clusters that are both joined and satisfying the rules will be selected. 


Make the note bold

britaniar · 2023-11-07T23:52:13Z

docs/api-references.md

+
+| Field | Description |
+| --- | --- |
+| `weight` _integer_ | Weight associated with matching the corresponding clusterSelectorTerm, in the range [-100, 100]. |


Explain what negative weight does vs positive.

michaelawyu · 2023-11-08T07:23:39Z

Hi @britaniar ! Thanks so much for the comments. The tricky part is, this is an auto-generated file; the contents are pulled from the comments in the source code through the journey of development, and to fix them we would need a separate PR to update the code, the CRDs, and release them first, which is a little bit difficult to follow through considering the timeframe and CCOA restrictions. If possible, I could keep your comments in a GitHub issue, and make the required edits when we are out of the embargo; would this be OK?

britaniar · 2023-11-08T17:15:33Z

Hi @britaniar ! Thanks so much for the comments. The tricky part is, this is an auto-generated file; the contents are pulled from the comments in the source code through the journey of development, and to fix them we would need a separate PR to update the code, the CRDs, and release them first, which is a little bit difficult to follow through considering the timeframe and CCOA restrictions. If possible, I could keep your comments in a GitHub issue, and make the required edits when we are out of the embargo; would this be OK?

I think that would be okay!

ryanzhang-oss · 2023-11-10T01:06:07Z

docs/api-references.md

+
+### Resource Types
+- [MemberCluster](#membercluster)
+- [MemberClusterList](#memberclusterlist)


do we need this?

ryanzhang-oss · 2023-11-10T01:07:52Z

docs/api-references.md

+- [ClusterResourceBinding](#clusterresourcebinding)
+- [ClusterResourcePlacement](#clusterresourceplacement)
+- [ClusterResourceSnapshot](#clusterresourcesnapshot)
+- [ClusterSchedulingPolicySnapshot](#clusterschedulingpolicysnapshot)
+- [Work](#work)
+- [WorkList](#worklist)


Can we order this list by the importance of the object like put CRP first followed by Work and the rest more internal fields.

ryanzhang-oss · 2023-11-10T01:08:04Z

docs/api-references.md

+- [ClusterResourceBinding](#clusterresourcebinding)
+- [ClusterResourcePlacement](#clusterresourceplacement)
+- [ClusterResourceSnapshot](#clusterresourcesnapshot)
+- [ClusterSchedulingPolicySnapshot](#clusterschedulingpolicysnapshot)
+- [Work](#work)
+- [WorkList](#worklist)


can we move the list?

ryanzhang-oss · 2023-11-10T01:08:37Z

docs/api-references.md

+
+
+ClusterResourcePlacement is used to select cluster scoped resources, including built-in resources and custom resources, and placement them onto selected member clusters in a fleet. 
+ If a namespace is selected, ALL the resources under the namespace are placed to the target clusters. Note that you can't select the following resources: - reserved namespaces including: default, kube-* (reserved for Kubernetes system namespaces), fleet-* (reserved for fleet system namespaces). - reserved fleet resource types including: MemberCluster, InternalMemberCluster, ClusterResourcePlacement, ClusterSchedulingPolicySnapshot, ClusterResourceSnapshot, ClusterResourceBinding, etc. 


no, that's an internal object.

ryanzhang-oss

I need this link to link to Azure doc

michaelawyu changed the title ~~doc: Add API reference~~ docs: Add API reference Nov 6, 2023

ryanzhang-oss reviewed Nov 6, 2023

View reviewed changes

britaniar reviewed Nov 8, 2023

View reviewed changes

ryanzhang-oss reviewed Nov 10, 2023

View reviewed changes

add api reference doc

05e6063

ryanzhang-oss force-pushed the docs/api-ref branch from 4e2da86 to 05e6063 Compare November 10, 2023 19:34

Merge branch 'main' into docs/api-ref

19fee8e

ryanzhang-oss approved these changes Nov 10, 2023

View reviewed changes

ryanzhang-oss merged commit e95ee8a into Azure:main Nov 10, 2023
5 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Add API reference #592

docs: Add API reference #592

michaelawyu commented Nov 6, 2023

ryanzhang-oss Nov 6, 2023

michaelawyu Nov 6, 2023

michaelawyu Nov 6, 2023

michaelawyu Nov 6, 2023

britaniar Nov 7, 2023

britaniar Nov 7, 2023

britaniar Nov 7, 2023

britaniar Nov 7, 2023

britaniar Nov 7, 2023

ryanzhang-oss Nov 10, 2023

britaniar Nov 7, 2023

britaniar Nov 7, 2023

britaniar Nov 7, 2023

britaniar Nov 7, 2023

michaelawyu commented Nov 8, 2023

britaniar commented Nov 8, 2023

ryanzhang-oss Nov 10, 2023

ryanzhang-oss Nov 10, 2023

ryanzhang-oss Nov 10, 2023

ryanzhang-oss Nov 10, 2023

ryanzhang-oss left a comment



		### Resource Types
		- [InternalMemberCluster](#internalmembercluster)




		ClusterResourceBinding represents a scheduling decision that binds a group of resources to a cluster. It MUST have a label named `CRPTrackingLabel` that points to the cluster resource policy that creates it.



		ClusterResourcePlacement is used to select cluster scoped resources, including built-in resources and custom resources, and placement them onto selected member clusters in a fleet.
		If a namespace is selected, ALL the resources under the namespace are placed to the target clusters. Note that you can't select the following resources: - reserved namespaces including: default, kube-* (reserved for Kubernetes system namespaces), fleet-* (reserved for fleet system namespaces). - reserved fleet resource types including: MemberCluster, InternalMemberCluster, ClusterResourcePlacement, ClusterSchedulingPolicySnapshot, ClusterResourceSnapshot, ClusterResourceBinding, etc.




		Manifest represents a resource to be deployed on spoke cluster.




		PlacementPolicy contains the rules to select target member clusters to place the selected resources. Note that only clusters that are both joined and satisfying the rules will be selected.

docs: Add API reference #592

docs: Add API reference #592

Conversation

michaelawyu commented Nov 6, 2023

Description of your changes

How has this code been tested

Special notes for your reviewer

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

michaelawyu commented Nov 8, 2023

britaniar commented Nov 8, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ryanzhang-oss left a comment

Choose a reason for hiding this comment