What does $hide_from_docs mean in the .proto files


#1

samples/bookinfo/platform/kube/rbac/details-reviews-policy-permissive.yaml has the following Spec:

spec:
  subjects:
  - user: "cluster.local/ns/default/sa/bookinfo-productpage"
  roleRef:
    kind: ServiceRole
    name: "details-reviews-viewer"
  mode: PERMISSIVE

I wondered what ‘mode: PERMISSIVE’ means. It is not documented at istio.io. api/rbac/v1alpha1/rbac.pb.go flags it $hide_from_docs so this is not a problem with documentation.

Why are there fields in samples that are not documented? Aren’t users going to wonder what these fields mean and try to look them up and get discouraged?


#2

PERMISSIVE mode means that receiving services (details and reviews in the example) can accept both both types of traffic: plain text and TLS.

I can find a reference to that at: https://istio.io/docs/reference/config/istio.authentication.v1alpha1/#MutualTls-Mode


#3

mTLS can be STRICT or PERMISSIVE.

The undocumented Mode of a ServiceRoleBinding is ENFORCED or PERMISSIVE.

According to api/rbac/v1alpha1/rbac.proto the Enforcement Mode is “… used to verify new ServiceRoleBinding configs work as expected before rolling to production. RBAC engine only logs results from configs that are in permissive mode, and discards result before returning to the user.”

This is different from mTLS mode. I assume it is hidden for a good reason, but what is the reason? Deprecated? Not yet implemented?


#4

hmm, interesting. I was thinking that ServiceRoleBinding uses the same modes as mTLS. keen to know why we have two different set of mode.